@comitor/ui 0.9.1 → 1.0.0

package/README.md

@@ -8,16 +8,21 @@ component ghép sẵn và khung ứng dụng (shell) kiểu workspace × app.
 - Token brand nằm ở **`styles.css`** — đổi token, bump version, mọi app nhận cùng một thay đổi.
 - Server-component-friendly: `"use client"` chỉ nằm ở file thật sự cần.
 
-> Trạng thái: `0.2.0` — 51 primitive + 24 composite + 18 file shell + chart, đã qua **một đợt sửa theo
-> review** (tương phản màu theo WCAG, thang đổ bóng 4 bậc, a11y tầng shell, chuỗi hiển thị của Tier 2
-> override được) và **một đợt dọn bề mặt API** (0.1.0 chưa app nào import — lần cuối đổi/xoá tên mà
-> không ai phải viết codemod).
+> Trạng thái: `1.0.0` — 52 file primitive (Tier 1) · 31 file composite (Tier 2) · 25 file shell
+> (Tier 3) · 4 file chart.
 >
-> ⚠ **`0.2.0` phá vỡ tương thích với `0.1.0`**: đổi tên hàm màu avatar, bỏ `avatarPalette` /
-> `LETTER_AVATAR_TONES` / `hashString` / `pickByString`, `useIsMac` chỉ còn một cửa, `DataTable` đổi
-> tên prop, và **giá trị một số token màu đã đổi**. Bảng chuyển đổi đầy đủ:
-> [CHANGELOG.md](CHANGELOG.md). Trong dải `0.x`, thay đổi phá vỡ tương thích đi kèm bump **minor**;
-> API chốt ở `1.0.0`.
+> Tài liệu đầy đủ: **https://design-system.comitor.ai** —
+> [Get started](https://design-system.comitor.ai/get-started) ·
+> [Components](https://design-system.comitor.ai/components) ·
+> [Composites](https://design-system.comitor.ai/composites) ·
+> [Shell](https://design-system.comitor.ai/shell) ·
+> [Changelog](https://design-system.comitor.ai/changelog) ·
+> [npm](https://www.npmjs.com/package/@comitor/ui).
+> README này là bản tra nhanh: cạm bẫy, hợp đồng màu, ranh giới server/client.
+>
+> API đã **chốt ở `1.0.0`**: từ đây thay đổi phá vỡ tương thích đi kèm bump **major**, không còn đi
+> kèm minor như dải `0.x` — mỗi mục breaking vẫn có bảng chuyển đổi ở
+> [changelog](https://design-system.comitor.ai/changelog).
 
 ---
 
@@ -44,24 +49,24 @@ pnpm add react-hook-form    # cho @comitor/ui/form
 | `recharts` | `>=2.15.0` | — | `/chart` (kiểu đã dựng cho **cả 2.x lẫn 3.x**, xem ghi chú dưới) |
 | `react-hook-form` | `^7.54.0` | — | `/form` (context singleton) |
 
-> **Vì sao `recharts` là `>=` chứ không phải `^`.** `^2.15.0` loại thẳng recharts 3 — mà 3.x
-> chạy tốt với gói này, nên app nào đã lên 3.x cũng ăn một dòng `unmet peer` không có cách sửa.
-> Kiểu của tầng `/chart` không còn dẫn xuất `payload`/`label` từ `TooltipProps`/`LegendProps`
-> của recharts (3.x đã bỏ hai trường đó khỏi props, chuyển sang context nội bộ) mà tự khai
-> `ChartPayloadItem` — phần giao của hai bản. `pnpm typecheck && pnpm build` được chạy **trên cả
-> recharts 2.15.4 lẫn 3.10.1** trước khi nới dải này.
->
-> `lucide-react` cũng là `>=` vì cùng lý do: thang phiên bản của nó nhảy `0.x` → `1.x` mà API
-> icon không đổi. Đã kiểm typecheck + build với `1.33.0`.
+> **Vì sao `recharts` và `lucide-react` là `>=` chứ không phải `^`.** `^2.15.0` loại thẳng recharts
+> 3 — mà 3.x chạy tốt với gói này: kiểu của tầng `/chart` không dẫn xuất `payload`/`label` từ
+> `TooltipProps`/`LegendProps` (3.x đã bỏ hai trường đó khỏi props) mà tự khai `ChartPayloadItem`,
+> phần giao của hai bản. Đã chạy `typecheck` + `build` trên **cả recharts 2.15.4 lẫn 3.10.1**.
+> `lucide-react` cũng vậy: thang phiên bản của nó nhảy `0.x` → `1.x` mà API icon không đổi, đã kiểm
+> với `1.33.0`.
 >
 > **Hiệu ứng vẽ dần của recharts 2.15.x hỏng với React 19.2**, nên `ComitorAreaChart` /
-> `ComitorBarChart` / `ComitorLineChart` mặc định **tắt** hiệu ứng từ `0.2.2` (§4.4). Nếu tự lắp
-> recharts trong `<ChartContainer>` thì gói không tắt hộ được — app phải tự ghi
-> `isAnimationActive={false}` lên từng `<Bar>`/`<Line>`/`<Area>` (§4.4 mục 1b).
+> `ComitorBarChart` / `ComitorLineChart` mặc định **tắt** hiệu ứng (§4.2). Nếu tự lắp recharts
+> trong `<ChartContainer>` thì gói không tắt hộ được — app phải tự ghi `isAnimationActive={false}`
+> lên từng `<Bar>`/`<Line>`/`<Area>` (§4.2).
+
+Cài đặt từng bước, kèm bản mẫu app: https://design-system.comitor.ai/get-started
 
 ## 2. Nạp `styles.css` — ĐỌC KỸ, đây là chỗ dễ sai nhất
 
-Đặt import trong **`app/globals.css`**, ngay sau `@import "tailwindcss"`:
+`styles.css` phải nằm trong **`app/globals.css`**, ngay sau `@import "tailwindcss"` — không phải
+`import` trong `layout.tsx` (`layout.tsx` chỉ import `globals.css` của chính app):
 
 ```css
 /* app/globals.css */
@@ -69,670 +74,118 @@ pnpm add react-hook-form    # cho @comitor/ui/form
 @import "@comitor/ui/styles.css";
 ```
 
-```ts
-// app/layout.tsx — chỉ import globals.css của chính app
-import "./globals.css";
-```
-
 > **KHÔNG** viết `import "@comitor/ui/styles.css"` trong `layout.tsx` (thói quen Tailwind 3).
 > File này chứa `@theme` / `@custom-variant` / `@source` — những at-rule **chỉ có nghĩa khi được
 > Tailwind biên dịch**. Import ở `layout.tsx` thì biến CSS vẫn chạy nhưng **không utility nào**
 > (`bg-gold-300`, `dark:*`…) được sinh ra → giao diện vỡ mà không có lỗi build.
 
-`styles.css` đã tự khai `@source "./dist"` để Tailwind quét class trong package (Tailwind v4 mặc
-định bỏ qua `node_modules`). Nếu dùng pnpm strict và thấy style bị mất, khai thêm ở app:
-
-```css
-@source "../node_modules/@comitor/ui/dist";
-```
-
-### Font
-
-App tự nạp Inter (subsets `latin` + `vietnamese`) và gán vào biến `--font-inter`; package chỉ tiêu thụ:
-
-```ts
-// app/layout.tsx
-import { Inter } from "next/font/google";
-
-const inter = Inter({
-  subsets: ["latin", "vietnamese"],
-  weight: ["400", "500", "600", "700", "800"],
-  display: "swap",
-  variable: "--font-inter"
-});
-```
-
-Package đọc **hai** biến font, cả hai đều tuỳ chọn:
-
-| Biến | Ai gán | Không gán thì sao |
-|---|---|---|
-| `--font-inter` | app (như trên) | `--font-sans` rơi về `"Inter", system-ui, sans-serif` — vẫn đúng nếu máy có Inter |
-| `--font-inter-mono` | app, **nếu muốn** đổi font chữ đều (số trong tooltip biểu đồ, `Kbd`…) | `--font-mono` rơi về `"Geist Mono", ui-monospace, monospace` |
-
-`--font-inter-mono` được tiêu thụ dưới dạng `var(--font-inter-mono, "Geist Mono")` — **fallback nằm ngay
-trong `var()`** là bắt buộc: `var()` không có fallback mà biến lại chưa khai thì cả khai báo `--font-mono`
-thành *invalid at computed-value time*, và `font-mono` rơi về font kế thừa chứ **không** rơi về phần còn
-lại của danh sách. Muốn dùng font mono riêng thì gán y hệt cách gán `--font-inter`:
+Dùng pnpm strict mà thấy mất sạch style thì khai thêm ở app:
+`@source "../node_modules/@comitor/ui/dist";` (gói đã tự khai `@source "./dist"`; Tailwind v4 mặc
+định bỏ qua `node_modules`).
 
-```ts
-const mono = Geist_Mono({ subsets: ["latin"], display: "swap", variable: "--font-inter-mono" });
-```
-
-### Dark mode
-
-Theo **class** (`@custom-variant dark (&:is(.dark *))`), khớp `next-themes`:
-
-```tsx
-<ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
-```
+**Font**: app tự nạp Inter (subsets `latin` + `vietnamese`) và gán `--font-inter`; gói chỉ tiêu thụ.
+`--font-inter-mono` là tuỳ chọn, gán y hệt cách gán `--font-inter` nếu muốn đổi font chữ đều (số
+trong tooltip biểu đồ, `Kbd`…). Không gán thì mỗi biến rơi về fallback khai sẵn trong `styles.css`.
+Cách gán bằng `next/font`: https://design-system.comitor.ai/get-started
 
-Lưu ý: biến thể `dark` chỉ khớp **con cháu** của `.dark`, không khớp chính phần tử mang class đó.
-Muốn dựng preview 2 theme cạnh nhau phải bọc thêm một lớp: `<div class="dark"><div>…</div></div>`.
+**Dark mode** theo **class** (`@custom-variant dark (&:is(.dark *))`), khớp `next-themes`. Lưu ý:
+biến thể `dark` chỉ khớp **con cháu** của `.dark`, không khớp chính phần tử mang class đó. Muốn dựng
+preview 2 theme cạnh nhau phải bọc thêm một lớp: `<div class="dark"><div>…</div></div>`.
+Cách dựng `ThemeProvider`, thứ tự lồng với `ContrastProvider`, và `suppressHydrationWarning` bắt
+buộc ở thẻ `<html>`: https://design-system.comitor.ai/shell
 
 ## 3. Entry point
 
-Package có **5 entry**. Lý do tách: `tsup` build ở chế độ `bundle: false` (ESM per-file), nên chỉ cần
-barrel chính re-export **một** file có `import` tới peer optional là mọi app dùng `@comitor/ui`
-đều buộc phải cài gói đó — không cài thì bundler gãy ngay ở bước resolve.
+Package có **5 entry**, tách theo peer optional mà mỗi tầng kéo theo:
 
 | Entry | Nội dung | Peer optional kéo theo |
 |---|---|---|
 | `@comitor/ui` | Tier 1 (primitive) + Tier 2 (composite) + `cn` + token TS + `useIsMac` | **không có** — chạy được ở Vite, Storybook, test runner |
-| `@comitor/ui/shell` | Tier 3: `AppShell`, `Sidebar`, `AppHeader`, `WorkspaceSwitcher`, `AppLauncher`, `UserMenu`, `ThemeProvider`, `SonnerToaster` | `next`, `next-themes` |
-| `@comitor/ui/chart` | `Chart*` (shadcn) + `ComitorAreaChart/BarChart/LineChart` + `CHART_COLORS` | `recharts` (~100KB) |
-| `@comitor/ui/form` | Binding shadcn ⇄ react-hook-form: `Form`, `FormField`, `FormItem`, `FormControl`, `FormMessage`, `useFormField` | `react-hook-form` |
-| `@comitor/ui/tokens` | Token dạng object TS | không — cho nơi không có Tailwind: canvas, email HTML, PDF |
-| `@comitor/ui/styles.css` | Nguồn token Tailwind v4 | xem §2 |
-
-### Tên xuất hiện ở nhiều entry
-
-Số tên mỗi entry xuất ra (đo bằng trình biên dịch TypeScript trên đúng 5 file entry, giải alias về khai
-báo gốc — không đếm tay): `.` **637** · `/shell` **70** · `/chart` **29** · `/form` **15** · `/tokens`
-**15**. Đúng **19 tên** xuất hiện ở nhiều hơn một entry, gom thành 4 nhóm dưới đây — `export *` chỉ báo
-đỏ khi trùng tên trong **cùng một** entry, nên trùng xuyên entry phải tra bằng bảng này:
-
-| Tên | Ở `@comitor/ui` | Ở entry khác | Cùng một cài đặt? |
-|---|---|---|---|
-| `FormField`, `FormFieldProps` | Tier 2 — bố cục 12 cột (label + control + mô tả + lỗi) | `/form` — wrapper của `Controller` (API shadcn) | **KHÔNG** — hai component khác hẳn nhau |
-| `normalizeVi` | `composite/text-utils.ts` | `/shell` — **re-export đúng bản đó** | **CÓ** — một thân hàm duy nhất (`0.2.0` gộp; trước đó là hai khai báo riêng giống nhau chữ-cho-chữ) |
-| `getVietnameseInitials` | `composite/text-utils.ts` (`toLocaleUpperCase("vi-VN")`) | `/shell` — **re-export đúng bản đó** | **CÓ** — một thân hàm duy nhất |
-| 15 token: `gold`, `ash`, `accent`, `accentInk`, `accentForeground`, `brandNeutral`, `semantic`, `status`, `chart`, `layout`, `typography`, `ThemeMode`, `getAvatarToneColors`, `getAvatarToneIndex`, `AvatarToneColors` | `export * from "./tokens.js"` | `/tokens` — **cùng một module** | **CÓ** — `/tokens` là tập con của `.`, tách ra cho nơi chỉ cần hằng số (email HTML, PDF, canvas) |
-
-Quy tắc dùng: hằng ngày lấy bản ở `@comitor/ui`; chỉ với tới `/form` khi app đã dùng react-hook-form.
-Chỉ `FormField` là thật sự hai component khác nhau, phải nhìn đúng entry.
-
-`0.2.0` đã dọn ba chỗ của `0.1.0`: **`useIsMac`** (từng có hai thân hàm khác nhau ở `.` và `/shell`)
-nay chỉ còn cửa `@comitor/ui`; **`avatarPalette`** (bảng màu avatar thứ hai) bị xoá; **`normalizeVi`**
-gộp về một binding. Còn đúng **`FormField`/`FormFieldProps`** là hai cài đặt khác nhau trong bảng trên
-— 16/18 tên còn lại đều trỏ vào cùng một binding. Xem [CHANGELOG.md](CHANGELOG.md).
-
-> **`Toaster` KHÔNG phải tên trùng.** Có hai toaster nhưng chúng mang hai tên: `Toaster` ở
-> `@comitor/ui` (toast có icon theo trạng thái, nhận prop `theme`) và **`SonnerToaster`** ở
-> `@comitor/ui/shell` (tự đọc `useTheme()` của next-themes). Dùng `SonnerToaster` khi app đã có
-> `ThemeProvider` của shell, còn lại dùng `Toaster`. Đừng gộp hai cái làm một.
-
-## 4. Ví dụ
-
-### 4.1 Trang nội dung — primitive + composite
-
-```tsx
-// Không có "use client": PageHeader/StatCard/StatusPill là component tĩnh → RSC render thẳng.
-import { PageContainer, PageHeader, StatCard, STATUS_TONES, StatusPill } from "@comitor/ui";
-import type { StatusConfig } from "@comitor/ui";
-
-// Bảng trạng thái là của APP, không phải của package — truyền vào qua `configs`.
-const TASK_STATUSES: StatusConfig<"todo" | "doing" | "done">[] = [
-  { value: "todo", label: "Cần làm", shortLabel: "CL", priority: 1, ...STATUS_TONES.neutral },
-  { value: "doing", label: "Đang làm", shortLabel: "ĐL", priority: 2, ...STATUS_TONES.info },
-  { value: "done", label: "Hoàn thành", shortLabel: "HT", priority: 3, ...STATUS_TONES.success }
-];
-
-export default function TasksPage() {
-  return (
-    <PageContainer width="lg">
-      <PageHeader title="Công việc" description="Toàn bộ task của workspace" />
-
-      <div className="grid gap-4 sm:grid-cols-3">
-        <StatCard
-          label="Đang mở"
-          value={128}
-          delta={{ value: "+12,5%", direction: "up", label: "so với tuần trước" }}
-        />
-        {/* polarity: quá hạn TĂNG là xấu → mũi tên lên phải tô đỏ, không tô xanh */}
-        <StatCard
-          label="Quá hạn"
-          value={7}
-          tone="destructive"
-          delta={{ value: "3 việc", direction: "up", polarity: "positive-down" }}
-        />
-        <StatCard label="Hoàn thành tuần này" value={43} tone="success" />
-      </div>
-
-      <StatusPill configs={TASK_STATUSES} value="doing" />
-    </PageContainer>
-  );
-}
-```
-
-### 4.2 Khung ứng dụng — `AppShell` + `WorkspaceSwitcher` + `AppLauncher`
-
-Shell dựng trên **hai trục điều hướng** kiểu Linear/Lark:
-
-- **Trục 1 — `WorkspaceSwitcher`**: đổi *ngữ cảnh dữ liệu* (Acme Corp ▸ Beta Ltd).
-- **Trục 2 — `AppLauncher`**: đổi *sản phẩm* trong cùng workspace (Tasks ▸ Chat ▸ CRM ▸ HR).
-
-Cả hai **không nhận dữ liệu qua prop** — chúng đọc từ context của `ShellProvider`, mà `AppShell`
-đã bọc sẵn. Vì vậy chỉ cần truyền `workspaces` / `apps` / `nav` một lần cho `AppShell`.
-
-```tsx
-// app/(app)/layout.tsx — root layout đặt ThemeProvider, layout con đặt AppShell.
-"use client";
-
-import { CheckSquare, LayoutDashboard, MessageSquare, Users } from "lucide-react";
-import { useRouter } from "next/navigation";
-import type { AppDescriptor, NavGroup, Workspace } from "@comitor/ui/shell";
-import { AppShell } from "@comitor/ui/shell";
-
-const workspaces: Workspace[] = [
-  { id: "acme", name: "Acme Corp", slug: "acme", plan: "Pro", role: "Quản trị viên", memberCount: 42 },
-  { id: "beta", name: "Beta Ltd", slug: "beta", plan: "Free", role: "Thành viên", memberCount: 6 }
-];
-
-const apps: AppDescriptor[] = [
-  { id: "tasks", name: "Công việc", icon: CheckSquare, href: "/tasks", accent: "var(--color-teal)" },
-  { id: "chat", name: "Trò chuyện", icon: MessageSquare, href: "/chat", badge: 3 },
-  { id: "crm", name: "CRM", icon: Users, href: "/crm", entitled: false } // chưa mua → hiện khoá
-];
-
-const nav: NavGroup[] = [
-  {
-    id: "main",
-    items: [
-      { id: "overview", label: "Tổng quan", href: "/tasks", icon: LayoutDashboard },
-      { id: "mine", label: "Của tôi", href: "/tasks/mine", icon: CheckSquare, badge: 12 }
-    ]
-  }
-];
-
-export default function AppLayout({ children }: { children: React.ReactNode }) {
-  const router = useRouter();
-
-  return (
-    <AppShell
-      workspaces={workspaces}
-      currentWorkspaceId="acme"
-      apps={apps}
-      currentAppId="tasks"
-      nav={nav}
-      user={{ id: "u1", name: "Nguyễn Đức Thành", email: "thanh@acme.vn", role: "Quản trị viên" }}
-      onWorkspaceChange={(id) => router.push(`/w/${id}`)}
-      onAppSelect={(app) => router.push(app.href)}
-      onUpsell={(appId) => router.push(`/billing?app=${appId}`)}
-      onLogout={signOut}
-    >
-      {children}
-    </AppShell>
-  );
-}
-```
-
-Cần tự lắp thay vì dùng `AppShell` trọn gói (vd header riêng)? Bọc `ShellProvider` rồi đặt
-`WorkspaceSwitcher` / `AppLauncher` ở đâu tuỳ ý — chúng vẫn lấy dữ liệu từ context:
-
-```tsx
-import { AppLauncher, ShellProvider, WorkspaceSwitcher } from "@comitor/ui/shell";
-
-<ShellProvider workspaces={workspaces} apps={apps} nav={nav} user={user}>
-  <header className="flex h-header items-center gap-2 px-3">
-    <WorkspaceSwitcher align="start" />
-    <AppLauncher />        {/* nút lưới 3×3, phím tắt ⌘/Ctrl + Shift + K */}
-  </header>
-  <main>{children}</main>
-</ShellProvider>
-```
-
-**Bọc `ThemeProvider` ở root layout, NGOÀI `AppShell`** — next-themes phải nằm trên cùng để không
-nháy theme lúc hydrate:
-
-```tsx
-// app/layout.tsx
-import { ThemeProvider } from "@comitor/ui/shell";
-
-<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
-  {children}
-</ThemeProvider>
-```
-
-App **không chạy trên Next**: truyền `pathname` và `LinkComponent` cho `ShellProvider`/`AppShell`
-để khỏi chạm `next/navigation`.
-
-#### Mục menu phân biệt nhau bằng query — prop `searchParams`
-
-`usePathname()` của Next **không bao giờ** chứa `?query`. Vì vậy mục khai
-`href: "/cai-dat?tab=thanh-vien"` được so bằng phần ĐƯỜNG DẪN (`/cai-dat`) — nó sáng khi bạn đang
-ở `/cai-dat`, và nếu menu có nhiều tab cùng đường dẫn thì **tất cả cùng sáng**, vì shell không
-thấy query.
-
-Muốn đúng từng tab thì đưa query cho shell qua prop **optional** `searchParams`:
-
-```tsx
-"use client";
-import { useSearchParams } from "next/navigation";
-import { AppShell } from "@comitor/ui/shell";
-
-export function Shell({ children }: { children: React.ReactNode }) {
-  const searchParams = useSearchParams();   // nhớ có <Suspense> ở trên trang
-  return <AppShell nav={nav} searchParams={searchParams}>{children}</AppShell>;
-}
-```
-
-Nhận cả `URLSearchParams`, chuỗi `"?tab=x"`, lẫn object `searchParams` của Server Component.
-Luật khi đã có nó:
-
-- mục có query sáng khi query của nó là **tập con** của URL hiện tại (`?tab=a` vẫn sáng ở
-  `?tab=a&q=abc&trang=2`);
-- mục **không** query nhường cho mục cùng đường dẫn có query khớp — tab mặc định không sáng cùng
-  lúc với tab đang mở;
-- luật cũ "chỉ `startsWith` khi không có mục nào khớp chính xác" giữ nguyên.
-
-> Shell **không** tự gọi `useSearchParams()`: hook đó ép trang phải bọc `<Suspense>` và đẩy trang
-> sang render phía client khi build tĩnh. Cái giá đó phải do app chọn, không phải hệ quả của việc
-> import shell.
-
-> **Từ `0.2.2`, cả 5 entry — kể cả `/shell` — nạp được bằng Node ESM thuần.** Ở `0.2.1` thì không:
-> `next@16` không khai `exports` map, nên với Node thì `next/link` chỉ là một đường dẫn file thiếu
-> đuôi và `import("@comitor/ui/shell")` chết ngay lúc nạp
-> (`ERR_MODULE_NOT_FOUND … Did you mean next/link.js?`), trong khi app Next không hề hấn vì bundler
-> tự thêm đuôi. Nay shell ghi thẳng `next/link.js` / `next/navigation.js` — **cùng một file** mà
-> bundler vẫn resolve tới, nên client-side navigation và `usePathname()` không đổi.
-> `pnpm smoke:entries` canh lại điều này ở mỗi lần publish.
-
-### 4.3 Token ngoài Tailwind
-
-```ts
-import { chart, getAvatarToneColors, layout, semantic } from "@comitor/ui/tokens";
-
-const seriesColor = chart.light[0];      // #E8B824
-const headerPx = layout.headerHeight;    // 56
-const errorText = semantic.dark.destructiveInk;  // mực đỏ trên nền tối
-
-// Avatar trong email HTML / canvas / PDF — cùng tone với avatar trên web
-const { background, foreground } = getAvatarToneColors("Nguyễn Đức Thành", "light");
-// { background: "#E0F2E9", foreground: "#216A48" }
-```
-
-> Hai cửa cho **một** bảng màu avatar: `getAvatarToneClasses(name)` ở `@comitor/ui` (có Tailwind → trả
-> chuỗi class, đổi theo theme) và `getAvatarToneColors(name, mode)` ở `@comitor/ui/tokens` (không có
-> Tailwind → trả hex đục đã trộn sẵn tint). Cùng bảng tone, cùng hàm băm, nên một người ra một màu ở cả
-> hai nơi. **Đừng** tự băm tên rồi bốc màu từ `accent` — đó là đường ngắn nhất để web và email lệch màu.
-
-### 4.4 Biểu đồ, và hằng của gói khi dùng ở Server Component
-
-Hai điều phải biết trước khi vẽ biểu đồ đầu tiên. Cả hai đều do app mẫu `comitor-starter` phát
-hiện bằng cách *dùng thật*, và cả hai đều IM LẶNG — không có lỗi, không có warning. Mục 1 có **hai
-nửa**: một nửa gói tự lo (`Comitor*Chart`), một nửa app phải tự lo (`ChartContainer` + recharts tự
-lắp) — đừng đọc nửa đầu rồi bỏ nửa sau.
-
-**1. Hiệu ứng vẽ dần mặc định TẮT (từ `0.2.2`).** Với `recharts` 2.15.x + React 19.2, hiệu ứng
-không bao giờ chạy tới khung hình cuối, nên mark đứng nguyên ở khung đầu — tức là vô hình. Đo trên
-DOM thật, ba dạng cùng một lỗi:
-
-| | biểu hiện trong SVG | thấy trên màn hình |
-|---|---|---|
-| `<Bar>` | `<g class="recharts-bar-rectangle">` **rỗng** (`Rectangle` trả `null` khi cao 0) | không có cột |
-| `<Line>` | path có `d` đúng nhưng `stroke-dasharray="0px 634px"` | không có đường |
-| `<Area>` | path có `d` đúng nhưng `<clipPath><rect width="0">` | không có vùng |
-
-Kết quả giống hệt nhau: đủ trục, đủ lưới, đủ chú giải, KHÔNG có dữ liệu — và chờ bao lâu cũng
-không tự hết. Nay ba component nhận prop **optional** `isAnimationActive`, mặc định `false`:
-
-```tsx
-<ComitorBarChart data={data} xAxisKey="thang" series={series} />          // hiện ngay
-<ComitorBarChart data={data} xAxisKey="thang" series={series} isAnimationActive />  // bật lại
-```
-
-Bật lại chỉ nên làm khi app chạy **recharts 3.x**; trên 2.15.x nó dựng lại đúng cái biểu đồ trống
-ở trên.
-
-**1b. Tự lắp recharts (`ChartContainer`) thì PHẢI TỰ TẮT — gói không đặt hộ được.** Mặc định mới ở
-trên chỉ có hiệu lực bên trong ba wrapper `Comitor*Chart`. Entry `/chart` còn một đường dùng thứ
-hai, đúng lối shadcn quen thuộc: `<ChartContainer>` + recharts do app tự lắp. Ở đường đó
-`<Bar>`/`<Line>`/`<Area>` là **children do app viết**, container không sờ vào được, nên trên
-`recharts` 2.15.x app gặp lại y nguyên lỗi im lặng của `0.2.1` — đủ trục, đủ lưới, KHÔNG có dữ liệu:
-
-```tsx
-"use client";
-import { ChartContainer } from "@comitor/ui/chart";
-import { Bar, BarChart, XAxis } from "recharts";
-
-// ✗ recharts 2.15.x — <g class="recharts-bar-rectangle"> rỗng, không cột nào
-<ChartContainer config={{ doanhThu: { label: "Doanh thu", color: "var(--chart-1)" } }}>
-  <BarChart data={data}>
-    <XAxis dataKey="thang" />
-    <Bar dataKey="doanhThu" fill="var(--color-doanhThu)" />
-  </BarChart>
-</ChartContainer>
-
-// ✓ tắt tay, trên TỪNG mark
-<Bar dataKey="doanhThu" fill="var(--color-doanhThu)" isAnimationActive={false} />
-<Line dataKey="doanhThu" stroke="var(--color-doanhThu)" isAnimationActive={false} />
-<Area dataKey="doanhThu" fill="var(--color-doanhThu)" isAnimationActive={false} />
-```
-
-Đo trên DOM thật (Next 16.3.2 · React 19.2.8 · recharts 2.15.4, `next build` + `next start`, chờ
-5000ms sau hydrate), cùng một trang chỉ khác một prop:
-
-| mark trong `<ChartContainer>` | thiếu prop | có `isAnimationActive={false}` |
-|---|---|---|
-| `<Bar>` | 3 `<g.recharts-bar-rectangle>`, **0** `path.recharts-rectangle` | **3/3** path, cao 273/410/342px |
-| `<Line>` | `stroke-dasharray="0px 818.84px"` | `stroke-dasharray` = `null` |
-| `<Area>` | `<clipPath><rect width="0">` | không còn rect `width="0"` |
-
-Trên **recharts 3.x** thì bỏ prop đi cũng được — lỗi không tồn tại ở đó. Nhưng dải peer của gói là
-`>=2.15.0`, nên cứ ghi `isAnimationActive={false}`: trên 3.x nó chỉ còn nghĩa "không hoạt hình".
-
-**2. `CHART_COLORS` (và mọi hằng khác của gói) đọc được từ Server Component.** Ở `0.2.1` thì
-không: hai hằng đó export từ `chart/comitor-chart.tsx`, mà file đó có `"use client"`. Bundler RSC
-cắt ranh giới theo FILE, nên mọi export của một module client tới phía server đều là
-client-reference proxy — `CHART_COLORS.gold` ra `undefined`, **không throw, không warning**, trong
-khi TypeScript vẫn khai kiểu literal. Kịch bản gãy đúng như JSDoc của gói đang khuyên viết:
-
-```tsx
-// page.tsx — Server Component
-const series = [{ key: "loi", color: CHART_COLORS.red }];   // 0.2.1: color = undefined (im lặng)
-```
-
-`0.2.2` chuyển **10 hằng** sang module không có directive (`chart/chart-colors.ts`,
-`components/composite/*-constants.ts`) và cho barrel xuất thẳng từ đó. Tên export không đổi, chỗ
-import không đổi:
-
-| Đọc từ Server Component | `0.2.1` | `0.2.2` |
-|---|---|---|
-| `CHART_COLORS.gold` | `undefined` | `"var(--chart-1)"` |
-| `CHART_SERIES_COLORS[0]` | `undefined` | `"var(--chart-1)"` |
-| `DEFAULT_DATA_TABLE_LABELS.emptyTitle` | `undefined` | `"Chưa có dữ liệu"` |
-| `VI_DATE_FORMAT` · `dateFormatForLocale(vi)` | `undefined` | `"dd/MM/yyyy"` |
-| `DEFAULT_DATE_PRESETS.length` | `0` | `3` |
-| `DEFAULT_DATE_RANGE_PRESETS.length` | `0` | `5` |
-| `DEFAULT_PAGE_SIZE_OPTIONS[0]` | `undefined` | `20` |
-| `SELECT_EMPTY_VALUE` | `undefined` | `"__empty__"` |
-| `DEFAULT_TABLE_PAGINATION_LABELS.region` | `undefined` | `"Phân trang"` |
-| `DEFAULT_SEARCH_FILTER_BAR_LABELS.searchPlaceholder` | `undefined` | `"Tìm kiếm…"` |
-
-`toSelectValue` / `fromSelectValue` đi cùng `SELECT_EMPTY_VALUE`, nên nay gọi được trong Server
-Action. `pnpm verify:directives` canh không cho hằng thuần lọt ngược vào file `"use client"`.
-
-> **Vẫn còn nằm sau ranh giới client — 13 tên, và tất cả đều BÁO LỖI TO, không im lặng.** Chúng là
-> hàm export từ file `"use client"`; gọi ở Server Component ném `Attempted to call <tên>() from the
-> server but <tên> is on the client`. Đã kiểm bằng trang Server Component prerender thật
-> (Next 16.3.2, `next build`, đọc HTML sinh ra trên đĩa): **13/13 ném đúng lỗi đó, 10/10 đối chứng
-> chạy bình thường**.
->
-> | | tên | vì sao vẫn ở đó |
-> |---|---|---|
-> | dựng chuỗi class (`cva`) | `buttonVariants`, `toggleVariants`, `fieldVariants`, `inputGroupAddonVariants`, `inputGroupButtonVariants` | sống cùng file với component client tương ứng |
-> | gọi lệnh toast | `toast`, `dismissToast`, `toastPromise` | vốn chỉ có nghĩa trong trình duyệt |
-> | hook | `useIsMac`, `useCarousel`, `useShell` (`/shell`), `useChart` (`/chart`), `useFormField` (`/form`) | hook thì đương nhiên client |
->
-> Nhóm đầu là nhóm dễ vấp nhất, vì chúng chỉ ghép chuỗi class — không có lý do trực giác nào để
-> chúng không chạy ở trang server. Muốn dựng class nút cho một `<a>` ở trang server thì để phần đó
-> trong một client component.
->
-> Chín helper `cva` còn lại **KHÔNG** kẹt — `alertVariants`, `badgeVariants`, `buttonGroupVariants`,
-> `cardVariants`, `emptyMediaVariants`, `itemVariants`, `itemMediaVariants`,
-> `navigationMenuTriggerStyle`, `statCardIconVariants`, cùng `cn`, đều gọi được từ Server Component
-> (đã đo cùng lượt, cùng trang). Danh sách trên là đầy đủ, không phải trích: nó dựng từ đồ thị
-> re-export của cả 5 entry, lọc mọi tên có giá trị runtime mà khai báo nằm trong file `"use client"`.
+| `@comitor/ui/shell` | Tier 3: khung ứng dụng workspace × app, theme, ba trục hiển thị | `next`, `next-themes` |
+| `@comitor/ui/chart` | Lớp shadcn bọc recharts + `Comitor*Chart` + `CHART_COLORS` | `recharts` (~100KB) |
+| `@comitor/ui/form` | Binding shadcn ⇄ react-hook-form | `react-hook-form` |
+| `@comitor/ui/tokens` | Token dạng object TS — cho nơi không có Tailwind: canvas, email HTML, PDF | không có |
+
+⚠ **20 tên xuất hiện ở nhiều hơn một entry**, và `export *` chỉ báo đỏ khi trùng trong **cùng một**
+entry — trùng xuyên entry thì im lặng hoàn toàn. Đúng **2** trong số đó là hai cài đặt khác nhau
+(`FormField` / `FormFieldProps`: ở Tier 2 là bố cục form 12 cột, ở `/form` là wrapper của
+`Controller`); 18 tên còn lại trỏ về cùng một binding nên lấy ở đâu cũng như nhau. Bảng đầy đủ, kèm
+hai ca **không** trùng tên hay bị tưởng nhầm (`Toaster` ⇄ `SonnerToaster`, và `useIsMac` chỉ xuất ở
+`@comitor/ui`): https://design-system.comitor.ai/get-started
+
+## 4. Cạm bẫy hay gặp
+
+### 4.1 Shell — hai trục, và mục menu phân biệt nhau bằng query
+
+Shell dựng trên **hai trục điều hướng**: `WorkspaceSwitcher` đổi *ngữ cảnh dữ liệu*
+(Acme Corp ▸ Beta Ltd), `AppLauncher` đổi *sản phẩm* trong cùng workspace (Tasks ▸ Chat ▸ CRM ▸ HR).
+Cả hai **không nhận dữ liệu qua prop** — chúng đọc context của `ShellProvider` mà `AppShell` đã bọc
+sẵn, nên `workspaces` / `apps` / `nav` chỉ truyền **một lần** cho `AppShell`.
+
+⚠ `usePathname()` của Next **không bao giờ** chứa `?query`. Vì vậy nhiều mục cùng đường dẫn
+(`/cai-dat?tab=a`, `?tab=b`) sẽ **cùng sáng** một lúc — không lỗi, không warning. Đưa query cho shell
+qua prop optional `searchParams` thì mỗi tab sáng đúng phần của nó.
+
+Cách lắp, toàn bộ luật active matching, và bản dùng ngoài Next:
+https://design-system.comitor.ai/shell · https://design-system.comitor.ai/components/sidebar-nav
+
+### 4.2 Biểu đồ — hiệu ứng vẽ dần, và ranh giới server/client
+
+⚠ Với **recharts 2.15.x + React 19.2**, hiệu ứng vẽ dần không bao giờ chạy tới khung hình cuối, nên
+mark đứng nguyên ở khung đầu — tức là vô hình: đủ trục, đủ lưới, đủ chú giải, **KHÔNG có dữ liệu**,
+và chờ bao lâu cũng không tự hết. `ComitorAreaChart` / `ComitorBarChart` / `ComitorLineChart` vì thế
+mặc định **tắt** hiệu ứng. Nhưng khi tự lắp recharts trong `<ChartContainer>` thì mark là children do
+app viết, container không đặt hộ được — app **phải tự ghi `isAnimationActive={false}` lên từng**
+`<Bar>` / `<Line>` / `<Area>`. Dải peer của gói là `>=2.15.0` nên cứ ghi: trên 3.x lỗi không tồn tại
+và prop chỉ còn nghĩa "không hoạt hình". https://design-system.comitor.ai/components/chart
+
+Ranh giới server/client là cạm bẫy cùng họ, và hỏng theo **hai kiểu ngược nhau**: 7 helper dựng chuỗi
+class (`buttonVariants`, `toggleVariants`…) gọi từ Server Component thì **ném lỗi to**, còn một hằng
+dữ liệu lọt vào sau file `"use client"` thì ra `undefined` — **không throw, không warning** — trong
+khi TypeScript vẫn khai kiểu literal. Danh sách đầy đủ 97 tên, ai gọi được ai không:
+https://design-system.comitor.ai/foundations/server-client
 
 ## 5. Bảng component
 
-Số liệu thực tế của `0.2.2`: **51 file primitive · 29 file composite · 18 file shell · 3 file chart**
-(chưa kể barrel) — số tên xuất ra theo entry: `.` **637** · `/shell` **70** · `/chart` **29** · `/form`
-**15** · `/tokens` **15** (xem §3 cho các tên xuất hiện ở nhiều entry). `0.2.2` **không thêm/bớt tên
-nào**; số file tăng vì hằng dữ liệu được tách sang module riêng (§4.4). Bảng dưới liệt kê component gốc;
-các thành phần con (`CardHeader`, `DialogFooter`, `SelectItem`…) export kèm theo file tương ứng.
-
-### Tier 1 — primitive (`@comitor/ui`)
-
-shadcn/ui style `new-york`, đã tùy biến token theo brand Comitor.
-
-| Nhóm | Component |
-|---|---|
-| Hành động | `Button`, `ButtonGroup`, `Toggle`, `ToggleGroup`, `Kbd` |
-| Nhập liệu | `Input`, `InputGroup`, `InputOTP`, `Textarea`, `Label`, `Field`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Select`, `Calendar` |
-| Hiển thị | `Card`, `Badge`, `Avatar`, `Table`, `Separator`, `AspectRatio`, `Skeleton`, `Spinner`, `Progress`, `Empty`, `Item`, `Alert` |
-| Lớp phủ | `Dialog`, `AlertDialog`, `Sheet`, `Drawer`, `Popover`, `HoverCard`, `Tooltip`, `DropdownMenu`, `ContextMenu`, `Menubar`, `Command` |
-| Điều hướng | `Tabs`, `Breadcrumb`, `Pagination`, `NavigationMenu`, `Accordion`, `Collapsible` |
-| Khác | `ScrollArea`, `Resizable`, `Carousel` |
-
-`Alert` có ba variant: `default` · `warning` · `destructive` — hai variant sau tô CHỮ bằng bậc `-ink`
-trên `bg-card`, không tô nền màu (bậc tô nền làm chữ chỉ được 1,59:1 ở light ✗).
-
-`Skeleton` tô bằng `--muted` (xám trung tính), KHÔNG phải `--accent`: bậc nhạt của brand là kem
-ngả vàng ở bảng light, nên cả một trang đang tải sẽ loang vàng — và đúng bằng màu mà `Switch`/`Tabs`
-dùng để nói "đang bật". Ở dark hai token vốn trùng giá trị nên không đổi gì.
-
-`Progress` có `tone`: `default` · `success` · `warning` · `destructive`. Tông `warning` KHÔNG chỉ đổi
-màu: nó kèm vạch chéo (`hazard-stripes`) khoét rãnh xuyên phần đã chạy. Bắt buộc phải thế, vì brand
-của Comitor là gold còn warning là yellow — `--warning-ink` ⇄ `--primary-ink` chỉ 1,00:1 ở bảng tương
-phản cao (light) và 1,0x:1 ở cả hai bảng dark, tức đổi màu KHÔNG đổi được gì. Vạch là cùng tín hiệu
-ấy nói bằng hình nên nó còn đọc ra ở chế độ xám (WCAG 1.4.1). Số đo và cách chứng minh "không hex nào
-tách được hai bậc ink này" ở chú thích đầu `progress.tsx`.
-
-> Hai file primitive **không** nằm ở entry chính: `form.tsx` → `@comitor/ui/form`;
-> `sonner.tsx` → `@comitor/ui/shell` (tên `SonnerToaster`). Xem §3.
-> **Không có `Sidebar` / `SidebarNav` ở Tier 1** — cố ý, không phải sót: shell Tier 3 đã có sidebar riêng
-> (hai trục điều hướng, thu gọn, nhớ trạng thái theo workspace) và bản shadcn sẽ trùng đúng 3 tên
-> `Sidebar` / `SidebarGroup` / `SidebarMenuItem` với Tier 3 nhưng API khác hẳn, lại giữ trạng thái bằng
-> cookie riêng. App nào thật sự cần bản shadcn thì `npx shadcn@latest add sidebar` vào repo của mình.
-> Lý do đầy đủ: [docs/quyet-dinh-tich-hop.md](docs/quyet-dinh-tich-hop.md) §17.
-
-#### `CardHeader` có nút ở góc phải — prop `actions`
-
-`CardHeader` mặc định xếp DỌC (`flex-col space-y-1.5`). Thẻ có nút ở góc phải vì thế phải ghi đè
-đúng một chuỗi bốn lớp, ở mọi app, mọi thẻ:
-
-```tsx
-/* ✗ Cách cũ — chép tay, dễ sót `space-y-0` (thiếu nó thì nút bị đẩy lệch xuống) */
-<CardHeader className="flex-row items-start justify-between gap-3 space-y-0">
-  <div>
-    <CardTitle>Thông tin đơn vị</CardTitle>
-    <CardDescription>Cập nhật lần cuối hôm qua</CardDescription>
-  </div>
-  <Button size="sm" variant="ghost">Sửa</Button>
-</CardHeader>
-
-/* ✓ Từ 0.2.1 — `actions` gói đúng chuỗi đó lại */
-<CardHeader actions={<Button size="sm" variant="ghost">Sửa</Button>}>
-  <CardTitle>Thông tin đơn vị</CardTitle>
-  <CardDescription>Cập nhật lần cuối hôm qua</CardDescription>
-</CardHeader>
-```
+Số file nguồn hiện tại: **52 primitive · 31 composite · 25 shell · 4 chart**. Mỗi component có trang
+riêng kèm demo, bảng prop và cạm bẫy của nó:
 
-Không truyền `actions` thì lớp và cây DOM **y hệt `0.2.0`** — prop này chỉ thêm một nhánh, không
-đổi mặc định. Cụm nút nhận `actionsClassName` riêng khi cần đổi `gap`/cho xuống dòng.
-
-Quan hệ với `CardAction`: `CardAction` là ô `ml-auto` để tự lắp khi bạn **đã** tự đặt header thành
-hàng ngang; `actions` làm cả hai việc (đổi bố cục *và* đặt chỗ) nên là đường đi mặc định.
-`CardAction` giữ nguyên cho ai đã dùng.
-
-### Tier 2 — composite (`@comitor/ui`)
-
-Giá trị thật của package: pattern lặp đi lặp lại ở mọi app, ghép từ nhiều primitive.
-
-| Component | Công dụng |
-|---|---|
-| `PageHeader`, `PageContainer` | Khung đầu trang (breadcrumb + hành động) và khung nội dung chuẩn |
-| `DataTable`, `DataTableColumnToggle` | Bảng dữ liệu: sort, chọn dòng, ẩn/hiện cột. Mọi chuỗi (kể cả `aria-label`) override được qua prop `labels` — xem `DataTableLabels` / `DEFAULT_DATA_TABLE_LABELS` |
-| `TablePagination` | Phân trang đi kèm bảng. Chuỗi override qua prop `labels` — `TablePaginationLabels` / `DEFAULT_TABLE_PAGINATION_LABELS` (khoá có số/đơn vị chèn vào là **hàm**, vd `range(start, end, total, unitLabel)`) |
-| `SearchFilterBar`, `FilterChips` | Thanh tìm + lọc + đếm kết quả. `SearchFilterBar` override chuỗi qua `labels` — `SearchFilterBarLabels` / `DEFAULT_SEARCH_FILTER_BAR_LABELS`; `FilterChips` nhận nhãn thẳng trong dữ liệu chip nên không có `labels` |
-| `StatCard`, `StatusPill`, `EmptyState` | Số liệu có delta, nhãn trạng thái, trạng thái rỗng |
-| `RouteTabs` | Tab mà mỗi mục là một **route thật** — `<nav>` chứa link, `aria-current="page"`. Dùng chung bảng lớp với `Tabs` nên nhìn không khác; đừng dùng `Tabs` cho việc này (nó dựng `role="tablist"` + `aria-controls` trỏ tới tabpanel cùng trang, mà ở đây không có). ⚠ Trên Next phải truyền `LinkComponent={Link}` |
-| `FormSection`, `FormField` | Bố cục form 12 cột; uỷ quyền label/mô tả/lỗi xuống `Field` |
-| `Combobox`, `MultiCombobox` | Chọn có tìm kiếm, **khớp không dấu tiếng Việt**. `aria-invalid` đổi trigger sang **viền đỏ** (`--destructive-ink`), cùng tín hiệu với `Input`; nhận cả `boolean` lẫn `"true"`/`"false"` để dùng thẳng `aria-invalid={!!errors.x}` |
-| `DatePicker`, `DateRangePicker` | Chọn ngày/khoảng ngày, preset dựng sẵn. **`locale?: Locale`** (date-fns, mặc định `vi`) đổi CẢ lịch lẫn thứ tự ngày/tháng của ô nhập: định dạng suy từ locale bằng `dateFormatForLocale()`, nên `en-US` ra `MM/dd/yyyy` mà không phải khai gì thêm. Ba nhãn `sr-only` override bằng `labels` |
-| `LetterAvatar`, `AvatarGroup` | Avatar chữ cái theo tên tiếng Việt (tông màu deterministic), nhóm người tham gia. Lấy tone bằng `getAvatarToneClasses(name)`; bản hex cho canvas/email/PDF là `getAvatarToneColors(name, mode)` ở `/tokens` — **cùng một bảng tone**, cùng một hàm băm |
-| `ConfirmDialog`, `CommandPalette` | Hộp xác nhận, bảng lệnh `⌘K` |
-| `Toaster`, `toast()`, `toastPromise()`, `dismissToast()` | Thông báo có icon theo trạng thái |
-| `CopyButton`, `RelativeTime`, `InlineEdit`, `KeyboardHint` | Tiện ích nhỏ dùng khắp nơi. `RelativeTime` nhận **`locale?: Locale`** (date-fns, mặc định `vi`) — app đa ngôn ngữ phải truyền, không thì giao diện tiếng Anh vẫn hiện "3 phút trước". Và `now?: Date` để đo từ một mốc CỐ ĐỊNH thay vì đồng hồ thật — dùng cho dữ liệu đứng yên (bản mẫu, ảnh chụp báo cáo, test); có `now` thì nó tự tắt hẹn giờ cập nhật và kết quả trở nên tất định |
-| `useIsMac` | Hook đi kèm `KeyboardHint` — `true` khi chạy trên macOS (render đầu luôn `false`, xem §3). **Cửa xuất duy nhất của cả gói**; `/shell` không re-export |
-
-Kèm 2 module thuần (không phải component, dùng được cả hai phía):
-
-| Module | Export |
-|---|---|
-| `status-config` | `STATUS_TONES`, `getStatusConfig`, `getStatusClasses`, `getStatusLabel`, `sortByStatusPriority` |
-| `text-utils` | `removeVietnameseTones`, `normalizeVi`, `matchesSearch`, `getVietnameseInitials`, `truncate` |
-
-> `text-utils` **không còn** `hashString` / `pickByString` (0.1.0 có). Hàm băm là chuyện nội bộ của phép
-> chọn tone avatar; xuất nó ra ngoài chỉ mời app dựng lại phép chọn của riêng mình — đúng thứ làm cùng
-> một người hiện hai màu ở web và email. Cần màu avatar thì dùng `getAvatarToneClasses` /
-> `getAvatarToneColors`; cần một màu tuỳ ý thì truyền `toneClassName` cho `LetterAvatar`.
-
-### Tier 3 — shell (`@comitor/ui/shell`)
-
-| Component | Công dụng |
-|---|---|
-| `AppShell` | Lắp sẵn `ShellProvider` + `Sidebar` + `AppHeader` + `<main>` + `MobileMenu`; hai layout `sidebar-first` / `header-first` |
-| `ShellProvider`, `useShell` | Context + phím tắt toàn cục; dùng khi tự lắp khung. (`useIsMac` **không** ở entry này — nhập từ `@comitor/ui`) |
-| `WorkspaceSwitcher` | **Trục 1** — đổi ngữ cảnh dữ liệu; dùng `Popover` (không `DropdownMenu`, vì typeahead của Radix cướp phím ô tìm kiếm) |
-| `AppLauncher`, `AppLauncherPanel` | **Trục 2** — lưới 3×3 đổi sản phẩm; app chưa mua hiện khoá và gọi `onUpsell` |
-| `AppHeader`, `Sidebar`, `SidebarGroup`, `SidebarMenuItem`, `MobileMenu` | Thành phần khung điều hướng |
-| `UserMenu`, `UserAvatar`, `NotificationsButton` | Vùng phải của header |
-| `ThemeProvider`, `ThemeToggle`, `SonnerToaster` | Theme sáng/tối (next-themes) + toast bám theme |
-| `ContrastProvider`, `ContrastToggle`, `useContrast`, `ContrastScript` | **Trục thứ hai của giao diện**: chọn BẢNG MÀU (bản duyệt comitor-ds ⇄ bản tương phản cao). Độc lập với sáng/tối; lưu ở localStorage `comitor-contrast`. Provider tự render script chống nháy — xem §6.0 |
-| `ShellNavLink` | Link nội bộ của shell; thay `next/link` bằng `LinkComponent` khi không chạy Next |
-| `ComitorLogo`, `ComitorLockup` | Vector brand — **không** có `"use client"`, RSC render thẳng (hex trong SVG là brand book, không tokenize) |
-| `DEFAULT_SHELL_LABELS` + `utils` | Chuỗi hiển thị mặc định (`ShellLabels`, 32 khoá); helper `flattenNavItems`, `isNavItemActive`, `isNavBranchActive`, `toNavGroups`, `resolveCurrentApp`, `getEntitledApps`, `getLockedApps`, `appAccentStyle`, `normalizeVi`, `getVietnameseInitials` |
-
-Hợp đồng dữ liệu (type): `Workspace`, `AppDescriptor`, `NavItem`, `NavGroup`, `ShellNav`, `ShellUser`,
-`UserMenuItem`, `ShellLabels`, `ShellIcon`, `ShellLinkComponent`.
-
-### Chart (`@comitor/ui/chart`)
-
-| Component | Công dụng |
-|---|---|
-| `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle`, `useChart` | Lớp shadcn bọc recharts (giữ tên trần theo API gốc). ⚠ Tự lắp `<Bar>`/`<Line>`/`<Area>` ở đây thì trên **recharts 2.15.x phải tự ghi `isAnimationActive={false}` lên từng mark** — container không đặt hộ được, quên là biểu đồ trống không báo lỗi (§4.4 mục 1b) |
-| `ComitorAreaChart`, `ComitorBarChart`, `ComitorLineChart` | Bản dựng sẵn theo brand — truyền `data` + `series` là xong |
-| `ComitorChartContainer`, `ComitorChartTooltip` | Bản tiện dụng; **có tiền tố `Comitor`** để không đụng tên trần ở trên |
-| `CHART_COLORS`, `CHART_SERIES_COLORS` | Bảng màu series mặc định — **hằng dữ liệu thuần, đọc được từ Server Component** (§4.4) |
-| `ChartColorName` | Khoá của `CHART_COLORS` |
-
-### Form (`@comitor/ui/form`)
-
-`Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `useFormField`
-— binding shadcn ⇄ react-hook-form. ⚠ `FormField` ở đây **khác** `FormField` của Tier 2 (§3).
-
-### Cơ chế `labels` — đổi ngôn ngữ mà không fork component
-
-Chuỗi hiển thị mặc định của gói là **tiếng Việt**, kể cả chuỗi chỉ trình đọc màn hình nghe thấy
-(`aria-label`, `sr-only`). App dùng ngôn ngữ khác override qua prop `labels` — không phải fork
-component, không phải bọc lại.
-
-| Component | Type | Hằng mặc định |
+| Tầng | Là gì | Trang |
 |---|---|---|
-| `DataTable`, `DataTableColumnToggle` | `DataTableLabels` | `DEFAULT_DATA_TABLE_LABELS` |
-| `TablePagination` | `TablePaginationLabels` | `DEFAULT_TABLE_PAGINATION_LABELS` |
-| `SearchFilterBar` | `SearchFilterBarLabels` | `DEFAULT_SEARCH_FILTER_BAR_LABELS` |
-| Toàn bộ Tier 3 (`AppShell`/`ShellProvider` truyền xuống) | `ShellLabels` (32 khoá) | `DEFAULT_SHELL_LABELS` |
-| `ThemeToggle` (dùng độc lập, ngoài shell) | `ThemeToggleLabels` = 4 khoá theme của `ShellLabels` | `DEFAULT_SHELL_LABELS` |
-
-Ba quy tắc chung cho mọi bộ nhãn:
-
-1. **`Partial<>` — override từng khoá.** Component luôn trải `{ ...DEFAULT_*, ...labels }`, nên truyền
-   một khoá không làm mất phần còn lại.
-2. **Khoá có số/đơn vị chèn vào là HÀM, không phải chuỗi có placeholder.** Nối chuỗi bằng dấu cộng ở
-   phía app là cách chắc chắn sai trật tự từ với ngôn ngữ khác:
-   `range(start, end, total, unitLabel)`, `pageStatus(page, pageCount)`, `filterCount(count)`,
-   `pageSizeSelect(unitLabel)`. `resultSummary` còn trả `ReactNode` vì con số cần thẻ riêng
-   (`tabular-nums` để số không nhảy cột).
-3. **Prop rời thắng `labels`.** `unitLabel`, `label`, `searchPlaceholder` vẫn là prop riêng và vẫn ghi
-   đè giá trị trong `labels`: chúng là chuỗi theo **nội dung** của từng bảng ("việc", "liên hệ"), còn
-   `labels` là chuỗi theo **ngôn ngữ** ("mục" / "items").
-
-```tsx
-const EN_PAGINATION: Partial<TablePaginationLabels> = {
-  region: "Pagination",
-  unitLabel: "items",
-  pageSizePrefix: "Show",
-  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_PAGINATION} unitLabel="contacts" />
-```
-
-`FilterChips` **không** có `labels` — nhãn của nó nằm thẳng trong dữ liệu chip, không có chuỗi nào chôn
-trong component.
+| **Tier 1 — primitive** · 52 file · `@comitor/ui` | shadcn/ui style `new-york`, đã tùy biến token theo brand Comitor | https://design-system.comitor.ai/components |
+| **Tier 2 — composite** · 31 file · `@comitor/ui` | Giá trị thật của gói: pattern lặp ở mọi app, ghép từ nhiều primitive (`DataTable`, `PageHeader`, `Combobox`, `DatePicker`, `StatCard`…) | https://design-system.comitor.ai/composites |
+| **Tier 3 — shell** · 25 file · `@comitor/ui/shell` | Khung ứng dụng workspace × app: sidebar, header, theme, ba trục hiển thị (tương phản · mật độ · cỡ chữ) | https://design-system.comitor.ai/shell |
+| **chart** · 4 file · `@comitor/ui/chart` | Lớp shadcn bọc recharts, cùng ba bản dựng sẵn theo brand | https://design-system.comitor.ai/components/chart |
+| **form** · `@comitor/ui/form` | Binding shadcn ⇄ react-hook-form | https://design-system.comitor.ai/components/form |
+
+**Cơ chế `labels` — đổi ngôn ngữ mà không fork component.** Chuỗi hiển thị mặc định của gói là **tiếng
+Việt**, kể cả chuỗi chỉ trình đọc màn hình nghe thấy (`aria-label`, `sr-only`); app dùng ngôn ngữ khác
+override qua prop `labels`. Kiểu là `Partial<>` và component luôn trải `{ ...DEFAULT_*, ...labels }`,
+nên truyền một khoá không làm mất phần còn lại. Component chỉ có một hai chuỗi thì mở bằng **prop
+rời** thay cho cả một object — `clearLabel`, `pendingLabel`, `overflowLabel`, `placeholder`,
+`emptyText`: cùng cơ chế, chỉ khác hình dạng. ⚠ Khoá có số/đơn vị chèn vào là **HÀM**, không phải
+chuỗi có placeholder (`range(start, end, total, unitLabel)`, `pageStatus(page, pageCount)`,
+`overflowLabel(count)`) — nối chuỗi bằng dấu cộng ở phía app là cách chắc chắn sai trật tự từ với
+ngôn ngữ khác.
 
 ## 6. Màu và token
 
-Toàn bộ token nằm ở [`styles.css`](./styles.css); bản mirror TS ở [`src/tokens.ts`](./src/tokens.ts).
-
-### 6.0 HAI bảng màu — đọc trước §6.1
-
-Gói có **hai** bảng màu, cùng một bộ component:
-
-| | Bật bằng | Là gì |
-|---|---|---|
-| **Mặc định** | (không cần gì) | Bảng của **comitor-ds** — repo design system đã được duyệt. Đây là nguồn sự thật về hình thức. |
-| **Tương phản cao** | `<html data-contrast="high">` | Bảng đã đo WCAG (chính là bảng của `0.2.x`). Dành cho màn hình độ sáng thấp, màn hình rẻ, hoặc dùng ngoài trời. |
-
-Bảng mặc định **cố ý có những cặp dưới ngưỡng** — đó là quyết định của người duyệt, không phải lỗi bỏ
-sót. Danh sách đầy đủ nằm ở khối `NGUỒN SỰ THẬT` đầu `styles.css`; những khoản chính:
-
-```
-viền checkbox/radio (--choice-edge)          2,99:1   (1.4.11 đòi 3:1)
-rãnh Switch BẬT, gạch active Tabs (gold)     1,86:1   (1.4.11 đòi 3:1)
---muted-foreground trên --muted              3,58:1   (1.4.3  đòi 4,5:1)
-chữ trắng trên nền --destructive             4,38:1   (1.4.3  đòi 4,5:1)
-Button variant link (--gold-400)             3,15:1   (1.4.3  đòi 4,5:1)
-```
-
-Hai ngoại lệ giữ bản sửa ở **cả hai** bảng, vì màu chữ của bản duyệt gần trùng màu nền tới mức không
-đọc nổi trên bất kỳ màn hình nào: `Badge` variant `warning` (1,52:1 → 6,24:1) và `success`
-(2,82:1 → 5,88:1). Nền giữ nguyên của bản duyệt, chỉ đậm chữ.
-
-**Cách bật trong app** — hai bước, app không sở hữu màu nào:
-
-```tsx
-// app/layout.tsx (Server Component)
-import { ContrastProvider, ThemeProvider } from "@comitor/ui/shell";
-
-<html lang="vi" suppressHydrationWarning>
-  <body>
-    <ThemeProvider>
-      <ContrastProvider>{children}</ContrastProvider>
-    </ThemeProvider>
-  </body>
-</html>
-```
-
-```tsx
-// trang cài đặt (client)
-import { ContrastToggle } from "@comitor/ui/shell";
-
-<ContrastToggle />
-```
+Nguồn token là `@comitor/ui/styles.css` (ship kèm gói, mở được ở
+`node_modules/@comitor/ui/styles.css`); bản mirror TS là entry `@comitor/ui/tokens`. Hai hợp đồng
+dưới đây là phần quan trọng nhất của gói — sai một trong hai thì hỏng **im lặng**, không có lỗi build.
 
-`ContrastProvider` tự render script chống nháy trong `<body>` — app **không** phải thêm gì vào
-`<head>`, và **đừng** đặt `<ContrastScript />` vào `<head>`: React 19 báo lỗi console ở mọi lần
-render client (script inline không nằm trong nhóm phần tử React hoisted được).
+**1. Có HAI bảng màu, dùng chung một bộ component.** Mặc định là bảng của **comitor-ds** — design
+system đã được duyệt, chính là bảng trên trang tài liệu, và là nguồn sự thật về hình thức. Bật
+`<html data-contrast="high">` thì đổi sang **bảng đã đo WCAG**, dành cho màn hình độ sáng thấp, màn
+hình rẻ, hoặc dùng ngoài trời. Bảng mặc định **cố ý có những cặp dưới ngưỡng**: đó là quyết định của
+người duyệt, không phải lỗi bỏ sót.
 
-> ⚠ **Điều kiện để hai bảng cùng sống**: mọi component đi qua **token vai trò**
-> (`--control-on`, `--control-edge`, `--control-check`, `--switch-track`, `--slider-track`,
+> ⚠ **Điều kiện để hai bảng cùng sống**: mọi component phải đi qua **token vai trò**
+> (`--control-on`, `--control-edge`, `--choice-edge`, `--switch-track`, `--slider-track`,
 > `--input-fill`, `--primary-ink`, `--link-ink`…) chứ **không** viết thẳng `bg-gold-300` /
-> `bg-ash-300` / `text-gold-400`. Viết thẳng thang màu là khoá cứng một bảng, và bảng kia lặng lẽ
-> sai. Cổng `pnpm lint:a11y` bắt được lỗi này vì nó đo **bảng tương phản cao**: giá trị viết thẳng
-> không đổi theo bảng nên sẽ hiện ra ở đó đúng bằng con số của bảng mặc định — tức là đỏ.
+> `bg-ash-300` / `text-gold-400`. Viết thẳng thang màu là khoá cứng một bảng, và bảng kia lặng lẽ sai.
 
-### 6.1 Hợp đồng BA VAI TRÒ của màu — đọc trước khi dùng bất kỳ màu nào
-
-Đây là quy tắc quan trọng nhất của gói. Mỗi màu có **ba** biến thể, đọc tên là biết dùng ở đâu:
+**2. Mỗi màu có BA vai trò** — đọc tên là biết dùng ở đâu:
 
 | Tên | Vai trò | Đo tương phản với | Ví dụ dùng |
 |---|---|---|---|
@@ -740,204 +193,51 @@ render client (script inline không nằm trong nhóm phần tử React hoisted
 | `--x-foreground` | chữ/icon **NẰM TRÊN** nền `--x` đặc | `--x` | `bg-destructive text-destructive-foreground` |
 | `--x-ink` | **chính màu đó** khi đi lên nền TRANG: chữ, icon rời, viền, vạch active | `--background` / `--card` / `--muted`, hoặc tint của chính nó | `text-teal-ink`, `border-red-ink` |
 
-**Vì sao phải có bậc `-ink` riêng thay vì dùng thẳng `--teal` / `--green` / `--red`**: bản light của màu
-phụ được chọn để tô **nền** nên quá nhạt cho vai trò chữ. Đo trên tint 15% của chính nó — nền thật mà
-chữ initials avatar và badge tonal đứng lên:
-
-```
-teal   #1F8A8B trên #DDEDEE = 3,44:1 ✗   →  --teal-ink  #1A6668 = 5,54:1 ✓
-green  #2EA56A trên #E0F2E9 = 2,69:1 ✗   →  --green-ink #216A48 = 5,60:1 ✓
-red    #D64545 trên #F9E3E3 = 3,57:1 ✗   →  --red-ink   #9A3537 = 5,83:1 ✓
-```
-
-Ở **dark** không có bậc riêng: `--x-ink` trỏ về `var(--x)`. Nhờ vậy `text-teal-ink` viết **một lần**
-là đúng cả hai theme, không cần biến thể `dark:`. Ở bảng **mặc định**, comitor-ds dùng cùng một hex cho
-cả hai theme nên bậc ink ở dark bằng bậc ở light; ở bảng **tương phản cao**, khối
-`.dark[data-contrast="high"]` nâng `--teal/--green/--red/--yellow` lên bậc sáng và `--x-ink` đi theo.
-
-> ⚠ Hợp đồng `-ink` chỉ còn ràng buộc chặt ở các cụm **tonal** mà comitor-ds không có (`Badge`
-> success/warning, `StatusPill`, `LetterAvatar`, `StatCard`, `Toast`) — đó là chỗ chữ đứng trên tint
-> của chính nó và bậc ink là thứ duy nhất giữ chữ đọc được. Với primitive **có** trong comitor-ds, bản
-> duyệt thắng: ở bảng mặc định `--primary-ink` = `--primary` và `--destructive-ink` = `--destructive`.
-
-Ba vai trò áp cho mọi họ token:
-
-| Họ | Nền | Chữ trên nền đó | Trên nền trang |
-|---|---|---|---|
-| Màu phụ | `--teal` `--green` `--red` `--yellow` `--navy` | — (dùng `--ink`/`--paper` tuỳ nền) | `--teal-ink` `--green-ink` `--red-ink` `--yellow-ink` `--navy-ink` |
-| Trạng thái | `--success` `--warning` `--info` `--destructive` | `--success-foreground` … `--destructive-foreground` | `--success-ink` `--warning-ink` `--info-ink` `--destructive-ink` |
-| Brand | `--primary` | `--primary-foreground` | `--primary-ink` |
-| Accent theo app | `--app-accent` | `--app-accent-foreground` | `--app-accent-ink` (mặc định `= --primary-ink`) |
-
-Brand cũng có bậc `-ink`, nhưng **giá trị của nó phụ thuộc bảng màu** (§6.0): gold `#E8B824` là màu
-**sáng** nên tô nền thì tuyệt, còn làm ranh giới trạng thái trên nền trang chỉ được **1,86:1**.
-comitor-ds chấp nhận con số đó, nên ở bảng mặc định `--primary-ink` = `--primary`; ở bảng tương phản
-cao nó mượn `--gold-500` `#7A5800` (**6,51:1** ✓ light) và trỏ về `--primary` ở dark (**12,67:1** ✓).
-⚠ `--control-on` KHÔNG còn trỏ vào `--primary-ink`: ở bảng tương phản cao chúng tách ra (`#B48700`
-so với `#7A5800`) vì `--primary-ink` còn phải làm CHỮ. Component vẫn viết `bg-control-on`. `--ring` **cố ý vẫn là** `--primary` ở cả hai bảng: vòng focus thuộc tiêu
-chí AAA của WCAG 2.2, ngoài mục tiêu của gói.
-
-Các lỗi hay gặp nhất, và cách sửa. **Số đo trong bảng là của bảng TƯƠNG PHẢN CAO** — đó là bảng có hợp
-đồng; ở bảng mặc định vài cặp thấp hơn theo đúng bản duyệt (§6.0):
-
-| Viết sai | Hỏng ở đâu | Viết đúng |
-|---|---|---|
-| `text-red` cho dòng báo lỗi | 4,38:1 ở light ✗; ở dark thì đây là thang brand thô | `text-destructive-ink` |
-| `text-success` / `text-info` / `text-warning` cho chữ hoặc icon trạng thái | Token TÔ NỀN: trên tint `/15` của chính nó chỉ 2,69:1 / 3,44:1 ✗ ở light; trên nền trang 3,13:1 / 4,14:1 ✗ | `text-success-ink` / `text-info-ink` / `text-warning-ink` (5,5–6,7:1 light · 7,1–12,4:1 dark) |
-| `bg-primary` / `bg-gold-300` làm rãnh `Switch` khi BẬT | Khoá cứng một bảng màu: bảng tương phản cao không đổi được nó nữa | `bg-control-on` |
-| `bg-ash-300` làm rãnh `Switch` khi TẮT, `bg-muted` làm rãnh `Slider` | Cùng lý do — thang màu thô không theo bảng | `bg-switch-track` / `bg-slider-track` |
-| `text-ink` làm dấu check của `Checkbox` | Khoá cứng một bảng: `--control-check` là thứ đi CẶP với `--control-on`, đổi bảng màu là nó tự theo | `text-control-check` |
-| `border-border` làm viền của control | `--border` là ranh giới **TRANG TRÍ** và cố ý ở dưới 3:1 tại MỌI bảng màu; `--control-edge`/`--choice-edge` mới là thứ chịu ngưỡng | `border-input` (= `--control-edge`), `border-choice-edge` cho Checkbox/Radio |
-| `bg-input/30` làm lớp tô ô nhập ở dark | Ở bảng tương phản cao `--input` là #7E8290, tô 30% ra mảng xám sáng làm placeholder tụt còn 3,22:1 ✗ | `dark:bg-input-fill` |
-| `text-app-accent` cho icon/vạch active | accent mặc định là gold `#E8B824` → 1,7–1,9:1 trên nền sidebar ✗ | `text-app-accent-ink`, hoặc nền ĐẶC + `text-app-accent-foreground` |
-| `text-destructive` cho chữ trên nền trang | `--destructive` là màu **NỀN**; ở bảng tương phản cao nó là bậc đậm cho chữ trắng đứng lên và làm chữ thì chỉ 3,76:1 ✗ ở dark | `text-destructive-ink` (7,15:1 light / 6,42:1 dark ở bảng tương phản cao; = `--destructive` ở bảng mặc định, đúng `text-destructive` của comitor-ds) |
-
-> ⚠ **App ghi đè `--app-accent` thì PHẢI set kèm `--app-accent-ink`** (và `--app-accent-foreground` nếu
-> accent sáng). Gói cố ý **không** dẫn xuất `-ink` bằng `color-mix` từ `--app-accent`: dẫn xuất tự động
-> cho ra con số tương phản không ai kiểm, và mỗi màu nền cần một hệ số khác nhau.
->
-> ⚠ **Ghi đè `--primary` thì nên set kèm `--primary-ink`** nếu app muốn một bậc tối riêng cho brand
-> của mình. Ở bảng mặc định hai biến này trùng nhau nên quên cũng không sai màu; ở bảng tương phản cao
-> thì `--primary-ink` điều khiển viền focus / gạch Tabs, còn control BẬT đi theo `--control-on`.
->
-> ⚠ **Đổi `--teal` / `--green` / `--red` thì phải tính lại bậc `-ink` tương ứng** — chúng là hex đã đóng
-> băng, không tự đi theo. Đóng băng là chủ ý: một chỗ duy nhất để đo lại, component không phải nhắc lại
-> chuỗi `color-mix(…)` (dễ chép lệch % giữa `Badge`/`LetterAvatar`/`Input`), và `tokens.ts` mirror được
-> ra hex thật cho canvas/email/PDF.
-
-Bản mirror TS đi theo đúng hợp đồng này: `accent` (nền) ⇄ `accentInk` (mực), `status.light.success` ⇄
-`status.light.successInk`, `semantic.light.destructive` ⇄ `semantic.light.destructiveInk`.
-
-### 6.2 Bảng token
-
-| Nhóm | Token | Ghi chú |
-|---|---|---|
-| Brand | `gold-50 … gold-600` | `gold-300 #E8B824` = `--primary` (light); dark nâng lên `gold-200 #F5D060`. `--primary-ink` = `--primary` ở bảng mặc định; ở bảng tương phản cao là `gold-500 #7A5800` (light) / `= --primary` (dark) — xem §6.0 và §6.1 |
-| Trung tính brand | `ink`, `ink-soft`, `paper`, `warm` | `warm #EDE8D8` = `--secondary` (light) |
-| Thang xám | `ash-50/100/300/500/700/900` | **Không phải `gray-*`** — xem cạm bẫy bên dưới |
-| Màu phụ (NỀN) | `navy`, `teal`, `red`, `green`, `yellow` | Vai trò **tô nền** (fill đặc hoặc tint). Bảng mặc định dùng một hex cho cả hai theme (đúng comitor-ds); bảng tương phản cao nâng sáng ở dark. ⚠ `--destructive` là token RIÊNG (nền nút xoá): `#D64545` ở bảng mặc định, `#C93B3B` ở bảng tương phản cao để chữ trắng đạt 5,03:1 |
-| Mực của màu phụ | `teal-ink`, `green-ink`, `red-ink`, `yellow-ink`, `navy-ink` | Cùng màu đó ở vai trò **chữ/icon/viền trên nền trang** — xem §6.1. Ở light là hex đã đóng băng (`#1A6668` / `#216A48` / `#9A3537` / `= gold-500` / `= navy`); ở dark trỏ về chính màu phụ |
-| Trạng thái | `success`, `warning`, `info`, `destructive` (+ `-foreground`, `-ink`, `destructive-hover`) | Ba cái đầu alias sang `green` / `yellow` / `teal`; `destructive` ghim một giá trị cho cả hai theme. `-ink` là bậc để làm **chữ** trạng thái. `--destructive-hover` phải là token riêng vì hai bảng đi **ngược chiều**: comitor-ds viết `hover:bg-red/90` (nhạt dần), bảng tương phản cao phải đậm thêm |
-| Ranh giới **ô nhập** | `control-edge`, `control-edge-strong`, `input`, `input-fill` | Input/Textarea/Select/Combobox/OTP, Button `outline`, Badge `outline`, rãnh Slider. `--control-edge` trỏ vào `--input`. Bảng mặc định light giữ đúng bậc của comitor-ds (`#EDEEF1`, 1,16:1) — ô nhập còn được nhận ra bằng kích thước, nhãn và placeholder. Dark thì **không** giữ được: `#1E2128` chỉ 1,10:1 trên `--card` nên đổi thành `#434A5A` (2,00:1). Bảng tương phản cao: `#7E8290` (3,83:1 / 4,64:1). `--control-edge-strong` = hover, `ash-300` light / `ash-500` dark đúng cặp bản duyệt |
-| Ranh giới **checkbox/radio** | `choice-edge`, `choice-edge-strong` | Tách riêng vì ở đây viền **là toàn bộ control** khi chưa chọn — không nhãn trong, không placeholder, không nền — nên nó chịu ngưỡng 1.4.11 còn viền ô nhập thì không. Bảng mặc định `#959597` (2,99:1) / `#5B6479` (3,00:1 trên `--card`); bảng tương phản cao trỏ thẳng về `--input`. Hover **không** dùng được `--control-edge-strong` (`ash-300` = 1,62:1, nhạt hơn cả lúc nghỉ) nên `--choice-edge-strong` là `ash-500` |
-| Control BẬT / ĐÃ CHỌN | `control-on`, `control-knob`, `control-check`, `switch-track`, `slider-track` | Rãnh `Switch` BẬT, ô `Checkbox` đã chọn, chấm `Radio`, đoạn `Slider`, ngày đang chọn của `Calendar` — tất cả dùng **cặp** `bg-control-on` + `text-control-check`; núm Switch là `bg-control-knob` (trắng ở cả hai bảng). Bảng mặc định `= --primary` (gold `#E8B824`); bảng tương phản cao `#B48700` — **vẫn là gold, chỉ đậm hơn**, đạt 3,28:1 ⇄ nền trang và 3,06:1 trên `--muted`. ⚠ KHÔNG dùng `gold-500 #7A5800`: đủ tương phản nhưng mắt đọc ra nâu-ô-liu, tức bảng màu thứ hai đổi luôn màu nhận diện. ⚠ Cũng KHÔNG kéo `--primary-ink` sáng theo — nó còn phải làm CHỮ (nhãn trạng thái, link) nên ở lại `gold-500`; đó chính là lý do `--control-on` và `--primary-ink` là hai token, dù ở mọi bảng khác chúng trùng giá trị |
-| Ranh giới **trang trí** | `border`, `sidebar-border` | Khung Card, đường kẻ bảng, vạch ngăn menu. **Không chịu ngưỡng nào** — nó chỉ tách khối cho mắt dễ quét. Bảng mặc định `#EDEEF1` / `#1E2128` (1,16:1 / 1,10:1) đúng comitor-ds; bảng tương phản cao nâng lên `#A4A4A6` / `#50586B` (**2,49:1** ở cả hai theme) — thấy rõ nhưng **cố ý thấp hơn viền control một bậc**, vì kéo nó lên ngang `--input` là mất phân cấp "thao tác được ⇄ chỉ là đường kẻ", và làm hỏng luôn 4 ca của `test:a11y-gate` vốn dựa vào việc token này ở dưới 3:1 để bắt lỗi "vẽ hình control bằng token trang trí" |
-| Link | `link-ink`, `link-ink-hover` | Button variant `link`. Tách khỏi `--primary-ink` vì comitor-ds dùng `gold-400` cho chữ link nhưng `gold-300` cho viền focus |
-| Biểu đồ | `chart-1 … chart-5` | Đổi bảng màu biểu đồ độc lập với brand. `chart-3` trỏ vào `--navy-ink` (nét biểu đồ phải NỔI trên nền trang) |
-| Avatar | `getAvatarToneColors(name, mode)`, `getAvatarToneIndex(name)`, type `AvatarToneColors` | Trả `{ background, foreground }` dạng **hex đục** cho canvas/email/PDF — đã trộn sẵn tint với nền `--card` vì ngoài CSS không có gì để hợp thành. Cùng bảng tone, cùng hàm băm với `getAvatarToneClasses(name)` ở `@comitor/ui`, nên một người luôn ra một màu ở mọi nơi. Khoá băm là **tên hiển thị**, không phải email/slug |
-| Theo app | `app-accent`, `app-accent-foreground`, `app-accent-ink` | Mỗi app Comitor tô một accent riêng — khai ở CSS của app (có nhánh `.dark`), không cần build lại package. Ghi đè `--app-accent` thì **phải** set kèm `--app-accent-ink` (§6.1) |
-| Hàng bảng | `table-row-stripe`, `table-row-hover` | Sọc xen kẽ và nền lúc rê chuột của `<Table striped>` / `<DataTable striped>`. **Đục, bắt buộc** — ô cột GHIM lấy nền bằng `bg-inherit` từ hàng, hàng còn alpha là ô ghim trong mờ và chữ của các cột đang cuộn lộ xuyên qua. Giá trị = `--muted` phủ 30% / 50% lên `--card`, đã hợp thành sẵn (`#FDFDFD` / `#FBFBFC` light, `#181B20` / `#1A1D23` dark) — đổi `--muted` hay `--card` thì tính lại |
-| Mật độ | `--row-py`, `--menu-item-py`, `--list-item-py`, `--nav-item-py`, `--table-head-h` | Toàn bộ đường bật của trục MẬT ĐỘ (`<html data-density="compact">`). Chỉ trục DỌC — "gọn" là thấy nhiều dòng hơn, không phải chữ dính vào mép. Dùng qua `py-(--row-py)` v.v. ⚠ Mọi token ở đây PHẢI có mặc định ở `:root`: cổng tương phản không đọc khối `[data-density]`, token vắng ở `:root` thì với nó là chuỗi rỗng và `measureShape` mất khả năng phân loại hình — hỏng **im lặng** |
-| Khung | `--sidebar-width`, `--sidebar-width-icon`, `--header-height` | Có utility `w-sidebar`, `w-sidebar-icon`, `h-header`. ⚠ Ba giá trị này tính bằng **rem** nên chúng PHÓNG THEO trục cỡ chữ; `layout` trong `@comitor/ui/tokens` mirror chúng bằng px và là số của mức **Vừa** |
-| Đổ bóng | `--elevation-surface`, `--elevation-control`, `--elevation-card`, `--elevation-overlay` | 4 bậc độ cao, sinh utility `shadow-surface` / `shadow-control` / `shadow-card` / `shadow-overlay`. Đổi theo theme (bản dark dùng đen thuần, alpha cao hơn) |
-| Khác | `--radius 6px` | Bo góc 6px là chữ ký thị giác. Viết bằng **px**, không phải `0.375rem`: trục cỡ chữ phóng theo tỉ lệ nên mọi giá trị rem đi theo — bo góc mà đi theo thì ở mức Lớn nó thành 6,75px |
-
-Đổi accent theo app — khai bằng **CSS, có nhánh dark**, không phải inline style trên `<body>`:
-
-```css
-/* app/globals.css — sau @import "@comitor/ui/styles.css" */
-:root {
-  --app-accent: #1f8a8b;            /* NỀN đặc                                        */
-  --app-accent-foreground: #0e1116; /* chữ trên nền đó         → 4,56:1 ✓             */
-  --app-accent-ink: #1a6668;        /* màu app trên nền trang  → 6,68:1 trên trắng ✓  */
-}
-.dark {
-  --app-accent: #2dd4bf;
-  --app-accent-foreground: #0e1116; /* 10,16:1 ✓                                      */
-  --app-accent-ink: #2dd4bf;        /* 10,16:1 trên --background ✓                    */
-}
-```
-
-Ba biến, không phải hai: bỏ `--app-accent-ink` thì icon/vạch active của app rơi về gold mặc định.
-Và phải khai ở CSS chứ không phải inline style vì **một giá trị inline không có nhánh `dark`** — accent
-sáng vừa đủ cho light mode thường quá tối trên nền `#0E1116`.
-
-> Trong `AppLauncher`, mỗi app còn tự tô ô icon của mình qua `AppDescriptor.accent` /
-> `accentForeground` (inline style, đúng vai trò nền + chữ-trên-nền). Ô icon dùng **nền đặc**, nên hai
-> biến đó là đủ; `--app-accent-ink` là chuyện của cả trang.
-
-Đổi độ nổi (bóng) toàn hệ — ghi đè đúng 4 biến `--elevation-*`, **không** ghi đè `--shadow-*`:
-
-```css
-/* app/globals.css — sau @import "@comitor/ui/styles.css" */
-:root { --elevation-overlay: 0 12px 40px rgba(14, 17, 22, 0.2); }
-```
-
-> Vì `--shadow-*` giữ giá trị dạng `var()`, Tailwind không tách được phần màu: `shadow-card/50` và
-> `shadow-<màu>` **không** có tác dụng. Đổi tông/độ đậm thì ghi đè `--elevation-*` như trên.
-
-### 6.3 Cạm bẫy phải nhớ
-
-1. **Nền hay mực? Chọn sai vai trò là hỏng tương phản, không phải hỏng thẩm mỹ.** `--x` tô nền,
-   `--x-ink` làm chữ/icon/viền trên nền trang (§6.1). Utility `text-teal` / `text-app-accent` **vẫn được
-   Tailwind sinh ra** — nó sinh cả bộ cho mọi `--color-*` — nên trình biên dịch sẽ không nhắc gì cả.
-2. **`ash-*` chứ không phải `gray-*`.** Thang xám Comitor chỉ có 6 bậc; nếu đặt tên `gray-*` thì
-   `gray-200/400/600/800` rơi về gray mặc định của Tailwind (ám xanh) và trộn với gray Comitor
-   (ám tím) → lệch tông. Đổi namespace để hai thang không đụng nhau.
-3. **Không sinh class động** (`` `bg-${color}-300` ``) ở bất kỳ đâu — Tailwind quét tĩnh, class động
-   bị loại khỏi bundle của app.
-4. **Không hardcode hex trong component** — trừ vector logo brand. Đọc hex từ `/tokens` rồi nhét vào
-   style inline là mất dark mode.
-5. `@theme **inline**` là chủ ý: `inline` nhúng thẳng `var(--x)` vào utility nên `.dark { --primary }`
-   đổi được màu tại runtime. Dùng `@theme` thường sẽ đóng băng giá trị lúc build → dark mode chết.
-
-## 7. Phát triển
-
-```bash
-pnpm install
-pnpm build        # tsup: ESM, bundle:false (transpile từng file để giữ "use client"), dts
-pnpm typecheck    # tsc --noEmit
-pnpm lint         # biome check .
-pnpm lint:fix
-pnpm lint:a11y           # hợp đồng màu: vai trò token + tương phản WCAG ở CẢ hai theme
-pnpm test:a11y-gate      # tự kiểm chính cổng trên: 56 khẳng định, cổng còn bắt đủ không
-pnpm test:nav-active     # active matching của sidebar (hàm thuần) — 34 ca
-pnpm verify:directives   # ranh giới server/client: directive còn sau build + không hằng thuần kẹt trong file client
-pnpm smoke:entries       # nạp cả 5 entry bằng Node ESM thuần, qua đúng `exports` map (chạy SAU build)
-pnpm check:exports       # publint --strict + attw
-```
-
-`pnpm test:nav-active` chạy `scripts/check-nav-active.mjs`: Node trần bóc kiểu ngay trên
-`src/shell/utils.ts`, không test runner, không dependency mới. Nó khoá lại đúng lỗi mà
-comitor-starter báo về ở `0.2.0` — mục menu có `?query` trong `href` không bao giờ sáng — cùng
-toàn bộ hành vi active matching cũ, để lần sửa sau không đổi ngầm luật nào.
-
-> Gặp `ERR_PNPM_IGNORED_BUILDS: esbuild` khi cài? Đã xử lý sẵn trong `pnpm-workspace.yaml`
-> (`allowBuilds: { esbuild: true }`) — pnpm 11 không còn đọc setting từ trường `pnpm` của
-> `package.json` nữa. esbuild cần chạy postinstall để nạp binary theo nền tảng, cấm chạy thì
-> `pnpm build` fail.
-
-Quy ước `"use client"`: đặt **per-file**, ở dòng đầu tiên. `tsup` chạy `bundle: false` nên mỗi file
-`.tsx` ra một file `.js` và directive được giữ nguyên → Next.js đánh đúng ranh giới server/client.
-File thuần dữ liệu (`lib/cn.ts`, `tokens.ts`, `shell/types.ts`) **không** có directive.
-
-`scripts/verify-directives.mjs` đi bộ **toàn bộ `src/`** (không riêng `shell/`): file nguồn nào mở đầu
-bằng `"use client"` thì file `dist/` tương ứng phải mở đầu y hệt — thiếu file build cũng tính là hỏng.
-Hiện **70/102** file nguồn cần directive, trải khắp cả composite lẫn primitive (`pnpm verify:directives`
-in ra đúng con số này — đừng chép số từ đây mà không chạy lại). Đừng thay script bằng
-`grep -L "use client" dist/shell/*.js`: lệnh đó soi chưa tới một phần ba số file phải soi.
-
-### Cổng hợp đồng màu — `pnpm lint:a11y`
-
-`scripts/check-contrast.mjs` quét **toàn bộ** `src/**/*.{ts,tsx}` theo QUY TẮC (không theo danh sách
-phát hiện) và đối chiếu với `styles.css`: token TÔ NỀN đem làm màu chữ/icon/viền là sai *vai trò*, và
-mọi cặp chữ/nền phải đạt 4,5:1 (chữ) hoặc 3:1 (thành phần phi văn bản) ở **cả** light lẫn dark.
-
-⚠ Cổng đo **bảng tương phản cao** (`:root` + `[data-contrast="high"]`), không đo bảng mặc định — bảng
-mặc định là bản duyệt và đã được chấp nhận với đúng những con số dưới ngưỡng ở §6.0; bắt nó là bắt một
-quyết định, và một cổng lúc nào cũng đỏ thì lần sau không ai chạy nữa. Hệ quả có lợi: component nào viết
-thẳng thang màu thay vì token vai trò sẽ đỏ ngay, vì giá trị viết thẳng không đổi theo bảng. Mọi loại
-phát hiện đều `exit 1` — kể cả lớp dùng bảng màu mặc định của Tailwind và miễn trừ đã thừa. Miễn trừ ghi
-ở `scripts/contrast-exemptions.json`, mỗi mục bắt buộc kèm lý do bằng chữ. Hợp đồng đầy đủ + giới hạn đã
-biết: [docs/hop-dong-mau.md](docs/hop-dong-mau.md).
-
-App tiêu thụ chạy được cùng cổng này trên bảng token đã ghi đè của mình: lấy script từ repo rồi trỏ
-`COMITOR_UI_STYLES` / `COMITOR_UI_SRC` sang file của app (script **không** nằm trong tarball npm).
-
-Trước khi phát hành: bump `version`, ghi mục mới trong [CHANGELOG.md](CHANGELOG.md), rồi chạy lại **cả
-khối lệnh ở đầu mục này** (`lint` và `lint:fix` là hai dạng của cùng một bước) — quy trình đầy đủ ở
-[CLAUDE.md](CLAUDE.md) §Publish.
+Phải có bậc `-ink` riêng vì bản light của màu phụ được chọn để tô **nền** nên quá nhạt cho vai trò
+chữ — `--teal` trên tint 15% của chính nó chỉ **3,44:1** ✗, còn `--teal-ink` được **5,54:1** ✓. Ở
+**dark** không có bậc riêng: `--x-ink` trỏ về `var(--x)`, nhờ vậy `text-teal-ink` viết **một lần** là
+đúng cả hai theme, không cần biến thể `dark:`. ⚠ Chọn sai vai trò thì **không có gì báo**: utility
+`text-teal` / `text-app-accent` vẫn được Tailwind sinh ra như thường.
+
+> ⚠ **App ghi đè `--app-accent` thì PHẢI set kèm `--app-accent-ink`** (và `--app-accent-foreground`
+> nếu accent sáng), khai bằng **CSS có nhánh `.dark`** chứ không phải inline style — một giá trị
+> inline không có nhánh dark. Gói cố ý **không** dẫn xuất `-ink` bằng `color-mix`: dẫn xuất tự động
+> cho ra con số tương phản không ai kiểm. Cùng luật đó khi đổi `--teal` / `--green` / `--red` — chúng
+> là hex đã **đóng băng**, không tự đi theo.
+
+Bảng token đầy đủ, bản đối chiếu viết-sai ⇄ viết-đúng, cách bật bảng tương phản cao, và mọi số đo:
+https://design-system.comitor.ai/foundations/colors
+
+## 7. Kiểm định trước mỗi lần phát hành
+
+Mỗi bản publish đi qua cùng một chuỗi cổng (`prepublishOnly` nối chúng lại): typecheck → build →
+`verify:directives` → `smoke:entries` → `check:exports` → `test:nav-active` → `test:a11y-gate` →
+`lint:a11y`. Những cổng đáng để người dùng gói biết là chúng tồn tại:
+
+- **`lint:a11y` — hợp đồng màu.** Quét **toàn bộ** `src/**/*.{ts,tsx}` theo QUY TẮC (không theo danh
+  sách phát hiện) và đối chiếu với `styles.css`: token TÔ NỀN đem làm màu chữ/icon/viền là sai
+  *vai trò*, và mọi cặp chữ/nền phải đạt 4,5:1 (chữ) hoặc 3:1 (thành phần phi văn bản) ở **cả**
+  light lẫn dark. Cổng đo **bảng tương phản cao** (`:root` + `[data-contrast="high"]`), không đo
+  bảng mặc định — bảng mặc định là bản duyệt và đã được chấp nhận với đúng những con số dưới ngưỡng
+  ở §6; bắt nó là bắt một quyết định, và một cổng lúc nào cũng đỏ thì lần sau không ai chạy nữa.
+  Mọi loại phát hiện đều `exit 1`, kể cả lớp dùng bảng màu mặc định của Tailwind và miễn trừ đã
+  thừa; miễn trừ mỗi mục bắt buộc kèm lý do bằng chữ.
+- **`verify:directives` — ranh giới server/client.** File nguồn nào mở đầu bằng `"use client"` thì
+  file `dist/` tương ứng phải mở đầu y hệt (thiếu file build cũng tính là hỏng), và không hằng dữ
+  liệu thuần nào được kẹt trong file client (§4.2).
+- **`smoke:entries`** nạp cả 5 entry bằng Node ESM thuần, qua đúng `exports` map (§3).
+- **`test:a11y-gate`** tự kiểm chính cổng màu (cổng còn bắt đủ không); **`test:nav-active`** khoá
+  toàn bộ luật active matching của sidebar dưới dạng hàm thuần (§4.1).
+
+Quy ước `"use client"` của gói: đặt **per-file**, ở dòng đầu tiên, và directive được giữ nguyên
+trong `dist/` → Next.js đánh đúng ranh giới server/client. Module thuần dữ liệu (`lib/cn.ts`,
+`tokens.ts`, `shell/types.ts`) **không** mang directive nên đọc được từ Server Component (§4.2).
+
+App tiêu thụ chạy được cùng cổng màu trên bảng token đã ghi đè của mình: script nhận
+`COMITOR_UI_STYLES` / `COMITOR_UI_SRC` trỏ sang file của app. Nhưng script **không** nằm trong
+tarball npm — hợp đồng màu đầy đủ và các giới hạn đã biết ở
+https://design-system.comitor.ai/foundations/colors
 
 ## 8. Giấy phép
 
-[MIT](./LICENSE) © Comitor
+MIT © Comitor