@vestow/vue 0.1.0

package/src/variants/README.md

@@ -0,0 +1,55 @@
+# `src/variants`
+
+Tầng **class** của WoodBlock: bảng `cva` của từng component, vòng focus, class
+dùng chung của menu, và `cn()`. TypeScript thuần — không import Vue, không
+import primitive nào.
+
+Đo lại hôm nay: **27 bảng `cva`** trong 22 file, và **0 bảng nằm trong file
+`.vue`**.
+
+Nó TỪNG là package riêng `src/variants`, tách ra để bản React đọc cùng
+một quyết định thiết kế. Đợt gộp đưa nó về đây vì repo chỉ còn cây Vue; ranh
+giới "không biết framework nào" thì giữ nguyên, và giữ vì nó vẫn có ích — một
+bảng class không nên biết mình đang được render bằng gì.
+
+(Tài liệu cũ ghi "18 bảng" ở sáu chỗ; đó là số FILE đeo nhãn số bảng — xem
+`../../../../CLAUDE.md`, mục về phép đếm này, kèm một dòng để đếm lại.)
+
+```ts
+import { buttonVariants } from '@vestow/vue/variants/components/button'
+import { cn } from '@vestow/vue/variants/lib/utils'
+
+cn(buttonVariants({ variant: 'destructive', tone: 'soft' }), props.class)
+```
+
+## Package này còn sở hữu ENTRY CSS
+
+`css/index.css` là entry dùng chung: Tailwind + token + **vùng quét của chính
+package này** (`@source "../src"`) + các khối `@layer` không thuộc framework nào
+(`.surface`, `.scroll-edge`, `.app-backdrop`, `.scroll-area-x`, reset base).
+`@vestow/vue` và `@vestow/react` đều import nó rồi chỉ thêm vùng quét
+riêng.
+
+`@source "../src"` là BẮT BUỘC và đã có lần quên: 27 bảng `cva` chuyển sang đây
+mà không khai vùng thì **155 class bị purge sạch** — build vẫn xanh, nút chỉ mất
+nền khi hover. Khai ở đây chứ không khai hộ từ `packages/ui`, vì `@source` phân
+giải tương đối theo file CSS chứa nó nên nó đúng cả khi package nằm trong
+`node_modules`.
+
+## Tiêu chí kết nạp
+
+Vào đây nếu nó quyết định **class nào được gắn**, và quyết định đó phải giống
+nhau ở mọi framework.
+
+Không vào đây: hàm hành vi (`isMacPlatform`, `moveItem`), kiểu bám framework
+(`ClassProps` đọc `HTMLAttributes` của Vue, `MenuActionItem.icon` là
+`Component` của Vue). Chúng ở lại `@vestow/vue`. Cần dùng chung thì mở một
+package khác — đừng nong package này ra khỏi đúng cái tên của nó.
+
+## Ràng buộc
+
+- **Chỉ CSS token, không giá trị cứng.** Class ở đây trỏ vào token của
+  `@vestow/theme`; hai package đi cùng nhau.
+- **Không phụ thuộc package private.** `extends` trong tsconfig viết đường dẫn
+  tương đối (`../tsconfig/lib.json`), không viết `@vestow/tsconfig` — pnpm
+  đổi `workspace:*` thành `0.0.0` lúc đóng gói.

package/src/variants/components/accordion.ts

@@ -0,0 +1,71 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+/**
+ * Hai kiểu trình bày, lấy mỗi bên một cái:
+ *
+ * - `plain` — các hàng ngăn nhau bằng một đường kẻ, không viền ngoài. Đây là
+ *   kiểu của shadcn, hợp khi accordion nằm sẵn trong một Card.
+ * - `contained` — mỗi mục là một tấm riêng có viền và nền. Đây là kiểu của
+ *   PrimeVue, hợp khi nó nằm thẳng trên nền trang.
+ *
+ * Hai thư viện gốc mỗi bên chỉ có một kiểu. Màn quản trị dùng cả hai chỗ nên
+ * giữ cả hai, đổi bằng prop thay vì bắt người dùng viết đè class.
+ */
+export const accordionVariants = cva('w-full', {
+  variants: {
+    variant: {
+      plain: '',
+      contained: 'flex flex-col gap-2',
+    },
+  },
+  defaultVariants: { variant: 'plain' },
+})
+
+export const accordionItemVariants = cva('', {
+  variants: {
+    variant: {
+      // `last:border-b-0` chứ không phải `not-last:border-b`: mục cuối vẫn cần
+      // đường kẻ khi accordion đứng trên một khối khác, chỉ bỏ khi nó là mục
+      // cuối của chính khối này.
+      plain: 'border-b border-border last:border-b-0',
+      contained: 'overflow-hidden rounded-xl border border-border bg-card',
+    },
+  },
+  defaultVariants: { variant: 'plain' },
+})
+
+export const accordionTriggerVariants = cva(
+  [
+    'group/accordion-trigger flex flex-1 items-start justify-between gap-3 py-3.5 text-left',
+    'text-sm font-medium transition-colors',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+    'disabled:pointer-events-none disabled:opacity-50',
+  ],
+  {
+    variants: {
+      variant: {
+        plain: 'rounded-md hover:underline',
+        contained: 'rounded-xl px-4 hover:bg-accent/60',
+      },
+    },
+    defaultVariants: { variant: 'plain' },
+  },
+)
+
+export const accordionContentVariants = cva(
+  // `overflow-hidden` bắt buộc: animation chạy bằng `height`, thiếu nó thì nội
+  // dung tràn ra ngoài suốt lúc đang trượt.
+  'overflow-hidden text-sm text-muted-foreground data-[state=open]:animate-accordion-down data-[state=closed]:animate-accordion-up',
+  {
+    variants: {
+      variant: {
+        plain: '',
+        contained: '',
+      },
+    },
+    defaultVariants: { variant: 'plain' },
+  },
+)
+
+export type AccordionVariants = VariantProps<typeof accordionVariants>

package/src/variants/components/alert.ts

@@ -0,0 +1,20 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+export const alertVariants = cva(
+  'relative grid w-full grid-cols-[auto_1fr] items-start gap-x-3 gap-y-1 rounded-lg border px-4 py-3 text-sm [&>svg]:size-4 [&>svg]:translate-y-0.5',
+  {
+    variants: {
+      variant: {
+        default: 'bg-card text-card-foreground border-border [&>svg]:text-muted-foreground',
+        info: 'border-info-soft-border bg-info-soft text-foreground [&>svg]:text-info-soft-foreground',
+        success: 'border-success-soft-border bg-success-soft text-foreground [&>svg]:text-success-soft-foreground',
+        warning: 'border-warning-soft-border bg-warning-soft text-foreground [&>svg]:text-warning-soft-foreground',
+        destructive: 'border-destructive-soft-border bg-destructive-soft text-foreground [&>svg]:text-destructive-soft-foreground',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+)
+
+export type AlertVariants = VariantProps<typeof alertVariants>

package/src/variants/components/badge.ts

@@ -0,0 +1,76 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+/**
+ * Hai trục giống `Button`: `variant` là **màu**, `tone` là **kiểu tô**.
+ * Badge không có `glass` — chip trạng thái không nằm trên media bao giờ.
+ */
+export const badgeVariants = cva(
+  'inline-flex items-center gap-1 rounded-md border font-medium whitespace-nowrap [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default: 'border-transparent bg-primary text-primary-foreground',
+        secondary: 'border-transparent bg-secondary text-secondary-foreground',
+        destructive: 'border-transparent bg-destructive text-destructive-foreground',
+        success: 'border-transparent bg-success text-success-foreground',
+        warning: 'border-transparent bg-warning text-warning-foreground',
+        info: 'border-transparent bg-info text-info-foreground',
+        outline: 'border-border text-foreground',
+      },
+      // `size` phải đứng TRƯỚC `tone` — cva nối class theo đúng thứ tự key ở
+      // đây, và quy ước chung của repo là trục KIỂU TÔ luôn nối sau trục CỠ.
+      //
+      // Chỉ có hai nấc, và đó là chủ ý: `default` là toàn bộ số đo vốn nằm trong
+      // chuỗi base, nên mọi chỗ đang gọi `badgeVariants()` nhận đúng chuỗi cũ.
+      // `xs` sinh ra cho nhãn phụ 9px trong hàng nav 30px — cỡ mặc định cao 22px,
+      // tức 73% chiều cao hàng, to ngang chính cái tên nó đang chú thích.
+      //
+      // Tên nấc theo `buttonVariants` và `chipVariants`: nấc giữa gọi là
+      // `default`, KHÔNG phải `md` — ba bảng cva dùng chung một từ vựng cỡ.
+      //
+      // KHÔNG thêm `sm` cho đủ bộ: chưa có chỗ nào đọc nó. Xem mục "tiêu chí
+      // kết nạp" ở CLAUDE.md — một nấc không người dùng là một lời hứa tương
+      // thích ngược không rút lại được.
+      size: {
+        // `leading-3` KHÔNG phải chỗ trang trí, và con số 3 (12px) không tuỳ tiện:
+        // `text-[9px]` là giá trị tuỳ ý nên Tailwind chỉ đặt `font-size`, giãn dòng
+        // rơi lui về 13.5px thừa kế. Line box 13.5px không lọt nổi content box 12px
+        // (14px trừ hai đường viền) nên chữ lệch LÊN — đo được mép trên hở 0,25px
+        // còn mép dưới 1,75px.
+        //
+        // 12px là ĐÚNG BẰNG content box. Đã quét cả thang: 13.5px lệch -1,5;
+        // `leading-none` (9px) vẫn lệch -1 vì font box của Geist cao 12px và tràn
+        // ra hai đầu line box; 10px / 12px / `normal` đều cho lệch 0 (hở 1px mỗi
+        // mép, đúng bằng đường viền). Chọn 12px vì nó là nấc có sẵn và nói thẳng
+        // ra quan hệ với chiều cao.
+        xs: 'h-3.5 px-1.5 text-[9px] leading-3 [&_svg]:size-2.5',
+        default: 'px-2 py-0.5 text-xs [&_svg]:size-3',
+      },
+
+      tone: {
+        solid: '',
+        soft: '',
+      },
+    },
+
+    // Nền pha loãng, chữ giữ nguyên sắc — kiểu "soft-danger" của Bootstrap.
+    // `outline` không có bản soft: nó vốn đã không có nền.
+    compoundVariants: [
+      { tone: 'soft', variant: 'default', class: 'border-primary-soft-border bg-primary-soft text-primary-soft-foreground' },
+      { tone: 'soft', variant: 'secondary', class: 'border-border bg-secondary text-secondary-foreground' },
+      { tone: 'soft', variant: 'destructive', class: 'border-destructive-soft-border bg-destructive-soft text-destructive-soft-foreground' },
+      { tone: 'soft', variant: 'success', class: 'border-success-soft-border bg-success-soft text-success-soft-foreground' },
+      { tone: 'soft', variant: 'warning', class: 'border-warning-soft-border bg-warning-soft text-warning-soft-foreground' },
+      { tone: 'soft', variant: 'info', class: 'border-info-soft-border bg-info-soft text-info-soft-foreground' },
+    ],
+
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+      tone: 'solid',
+    },
+  },
+)
+
+export type BadgeVariants = VariantProps<typeof badgeVariants>

package/src/variants/components/button-group.ts

@@ -0,0 +1,136 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+/**
+ * Gộp nhiều nút thành một khối liền mạch: bỏ bo góc ở các cạnh giáp nhau và
+ * gộp viền chung.
+ *
+ * Khác shadcn ở hai chỗ, cả hai đều có lý do:
+ *
+ * 1. **Chọn con bằng `:first-child` / `:last-child`, không bằng `[data-slot]`.**
+ *    shadcn đòi mọi phần tử con phải mang `data-slot`; ở đây một `<input>`,
+ *    một div viết tay hay `DropdownMenuTrigger` bọc `as-child` đều nằm trong
+ *    nhóm được mà không phải khai gì thêm.
+ * 2. **Chỉ TẮT bo góc ở cạnh trong, không ép lại bo góc ở cạnh ngoài.** shadcn
+ *    ghi đè `rounded-r-lg!` cho con cuối, nên nhóm toàn nút `size="sm"` (vốn
+ *    `rounded-md`) bị bo 8px thay vì 6px. Để nguyên thì mỗi nút giữ đúng bán
+ *    kính theo cỡ của nó.
+ *
+ * ## Trục `depth` — và vì sao nó tồn tại
+ *
+ * Cây vanilla dựng `<wb-button>` / `<wb-toggle>` ở chế độ shell: host mang
+ * `display: contents` và thẻ thật nằm bên trong. Selector `>` vẫn KHỚP cái host,
+ * nhưng host không tạo hộp nên `border-radius` áp vào hư không — khai báo đúng,
+ * kết quả không có gì. `vanilla/CLAUDE.md` ghi việc này thành một ràng buộc kiến
+ * trúc còn mở, với ba lối ra và không lối nào miễn phí.
+ *
+ * `depth: 'shell'` là lối thứ hai trong ba lối đó, và chọn nó vì phép so sánh
+ * nghiêng hẳn về một phía: cái giá của nó **đo được** (vài trăm byte CSS cho mọi
+ * app nạp bộ variants), còn cái giá của việc viết bản thứ hai chỉ cho vanilla là
+ * hai bộ luật trôi khỏi nhau — thứ cả repo này sinh ra để dập, và thứ không phép
+ * đo nào bắt được.
+ *
+ * Nó phát **cả hai cấp**, không phải chỉ cấp sâu: một nhóm ở light DOM trộn được
+ * con có hộp với con `display: contents`, và bảng này không biết trước cái nào
+ * là cái nào. Luật rơi vào một host `contents` thì không vẽ gì, nên phát thừa ở
+ * đó là vô hại — còn phát thiếu thì góc không bo và không có gì báo.
+ *
+ * Giới hạn phải nói ra: nó với được **đúng một** cấp. Chuỗi `contents` lồng hai
+ * lớp (`<wb-popover-trigger>` bọc `<wb-button>`) thì hụt, và cách xử lý là đừng
+ * lồng — xem `WbSplitButton` của cây vanilla.
+ *
+ * Mặc định vẫn là `direct`, nên ba cây kia không đổi một class nào ở đầu ra.
+ * **Đừng dùng `shell` cho `SplitButton`**: ở đó con trực tiếp đã là nút, và với
+ * sâu một cấp nữa là bắt trúng nút lồng trong nút.
+ */
+export const buttonGroupVariants = cva(
+  [
+    'flex w-fit items-stretch',
+    // Nút đang focus phải nổi lên trên, nếu không vòng focus bị nút bên cạnh
+    // đè mất một nửa — các nút chồng viền lên nhau.
+    '[&>*]:focus-visible:relative [&>*]:focus-visible:z-(--z-raised)',
+    // Lồng ButtonGroup trong ButtonGroup thì tách hai khối ra, không dính liền.
+    'has-[>[data-slot=button-group]]:gap-2',
+    '[&>input]:flex-1',
+  ],
+  {
+    variants: {
+      orientation: {
+        horizontal: '',
+        vertical: 'h-fit flex-col',
+      },
+
+      /**
+       * `direct` — con trực tiếp là thẻ có hộp (Vue, React, Angular).
+       * `shell` — con trực tiếp là một host `display: contents`, thẻ thật nằm
+       * sâu thêm một cấp (cây vanilla).
+       */
+      depth: {
+        direct: '',
+        // Vòng focus cũng phải với sâu một cấp: tiêu điểm nằm ở thẻ thật bên
+        // trong, nên `> *:focus-visible` của phần base không bao giờ khớp và nút
+        // đang focus bị nút bên cạnh đè mất một nửa quầng.
+        shell: '[&>*>*:focus-visible]:relative [&>*>*:focus-visible]:z-(--z-raised)',
+      },
+
+    },
+
+    compoundVariants: [
+      {
+        orientation: 'horizontal',
+        depth: 'direct',
+        class: [
+          '[&>*:not(:first-child)]:rounded-l-none',
+          '[&>*:not(:last-child)]:rounded-r-none',
+          // Viền trái của con sau trùng viền phải của con trước — bỏ một cái đi
+          // thay vì kéo âm lề, để bề rộng từng nút không đổi.
+          '[&>*:not(:first-child)]:border-l-0',
+        ],
+      },
+      {
+        orientation: 'vertical',
+        depth: 'direct',
+        class: [
+          '[&>*:not(:first-child)]:rounded-t-none',
+          '[&>*:not(:last-child)]:rounded-b-none',
+          '[&>*:not(:first-child)]:border-t-0',
+        ],
+      },
+      {
+        orientation: 'horizontal',
+        depth: 'shell',
+        class: [
+          // CẢ HAI cấp, không phải chỉ cấp sâu: một nhóm ở light DOM trộn được
+          // con có hộp (`<input>`, nhãn) với con `display: contents` (`<wb-button>`),
+          // và bảng này không biết trước cái nào là cái nào. Luật rơi vào một
+          // host `contents` thì không vẽ gì — vô hại — nên phát cả hai là đúng.
+          '[&>*:not(:first-child)]:rounded-l-none',
+          '[&>*:not(:last-child)]:rounded-r-none',
+          '[&>*:not(:first-child)]:border-l-0',
+          '[&>*:not(:first-child)>*]:rounded-l-none',
+          '[&>*:not(:last-child)>*]:rounded-r-none',
+          '[&>*:not(:first-child)>*]:border-l-0',
+        ],
+      },
+      {
+        orientation: 'vertical',
+        depth: 'shell',
+        class: [
+          '[&>*:not(:first-child)]:rounded-t-none',
+          '[&>*:not(:last-child)]:rounded-b-none',
+          '[&>*:not(:first-child)]:border-t-0',
+          '[&>*:not(:first-child)>*]:rounded-t-none',
+          '[&>*:not(:last-child)>*]:rounded-b-none',
+          '[&>*:not(:first-child)>*]:border-t-0',
+        ],
+      },
+    ],
+
+    defaultVariants: {
+      orientation: 'horizontal',
+      depth: 'direct',
+    },
+  },
+)
+
+export type ButtonGroupVariants = VariantProps<typeof buttonGroupVariants>

package/src/variants/components/button.ts

@@ -0,0 +1,160 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+import { focusRing } from '../lib/focus'
+
+/**
+ * Hai trục:
+ * - `variant` là **màu** (default, destructive, success…) — không đổi so với trước.
+ * - `tone` là **kiểu tô**: `solid` đặc, `soft` nền pha loãng.
+ *
+ * KHÔNG có tone `glass`: kính là vật liệu của BỀ MẶT (`data-surface="glass"`),
+ * bật lên thì mọi nút tự thành kính — xem surfaces.css. Apple cũng khuyến nghị
+ * dùng kính dè sẻn ở lớp điều hướng chứ không rải thành biến thể của nút.
+ *
+ * BẢNG NÀY CHỈ ĐỌC `--button-*`, không đọc token ngữ nghĩa nào nữa. Tầng token
+ * riêng của Button nằm ở `@vestow/theme/css/components/button.css`, và mỗi
+ * token ở đó mặc định trỏ vào một token dùng chung — nên đổi bảng màu vẫn chảy
+ * qua như cũ, chỉ khác là giờ ghi đè được RIÊNG cái nút.
+ *
+ * Hai con số từng là literal ngay trong file này — `0.97` của phép lún và `50%`
+ * của trạng thái disabled — nay là `--button-press-scale` và
+ * `--button-disabled-opacity`. Đó đúng là loại hằng số mà tầng token sinh ra để
+ * rút: chúng là quyết định thiết kế, không phải chi tiết cài đặt.
+ *
+ * `--ui-control-*` (chiều cao, đệm ngang) CỐ Ý không nhân bản sang `--button-*`:
+ * Toggle dùng chung thang đó theo đúng chủ ý đã ghi ở `CLAUDE.md`, tách ra là
+ * dựng lại chính thứ việc gom chúng sinh ra để dập.
+ */
+export const buttonVariants = cva(
+  [
+    // `ui-button` là móc để surfaces.css biến MỌI nút thành kính khi bật theme
+    // glass. Ngoài theme đó nó không khớp rule nào.
+    'ui-button inline-flex items-center justify-center gap-(--button-gap) whitespace-nowrap rounded-(--button-radius)',
+    'text-(length:--button-font-size) [font-weight:var(--button-font-weight)]',
+    // Lún nhẹ khi bấm. Màu đổi trong 140ms, riêng transform 100ms cho dứt khoát
+    // — đúng nhịp bản thiết kế khai. `disabled`/`loading` đã bị chặn con trỏ nên
+    // không vào được trạng thái :active.
+    'transition-[color,background-color,border-color,opacity,transform] duration-(--button-duration)',
+    'active:scale-(--button-press-scale) active:duration-(--button-press-duration) motion-reduce:active:scale-100',
+    // Cùng vòng focus với ô nhập, không phải một kiểu riêng cho nút. Bắt buộc
+    // phải vậy: trigger của DatePicker CHÍNH LÀ một Button, để hai kiểu khác
+    // nhau thì trong cùng một form sẽ có hai kiểu focus.
+    focusRing,
+    'disabled:pointer-events-none disabled:opacity-(--button-disabled-opacity)',
+    'aria-disabled:pointer-events-none aria-disabled:opacity-(--button-disabled-opacity)',
+    '[&_svg]:pointer-events-none [&_svg]:size-(--button-icon-size) [&_svg]:shrink-0',
+  ],
+  {
+    variants: {
+      variant: {
+        default: 'bg-(--button-default-bg) text-(--button-default-fg) hover:bg-(--button-default-bg-hover) active:bg-(--button-default-bg-active) [--btn-fill:var(--button-default-bg)] [--btn-fill-hover:var(--button-default-bg-hover)] [--btn-on-fill:var(--button-default-fg)] [--btn-soft:var(--button-default-soft-bg)] [--btn-soft-hover:var(--button-default-soft-bg-hover)] [--btn-on-soft:var(--button-default-soft-fg)] [--btn-on-soft-hover:var(--button-default-soft-fg-hover)] [--btn-line:var(--primary-soft-border)]',
+        secondary: 'bg-(--button-secondary-bg) text-(--button-secondary-fg) hover:bg-(--button-secondary-bg-hover) active:bg-(--button-secondary-bg-active) [--btn-fill:var(--button-secondary-bg)] [--btn-fill-hover:var(--button-secondary-bg-hover)] [--btn-on-fill:var(--button-secondary-fg)]',
+        destructive: 'bg-(--button-destructive-bg) text-(--button-destructive-fg) hover:bg-(--button-destructive-bg-hover) active:bg-(--button-destructive-bg-active) [--btn-fill:var(--button-destructive-bg)] [--btn-fill-hover:var(--button-destructive-bg-hover)] [--btn-on-fill:var(--button-destructive-fg)] [--btn-soft:var(--button-destructive-soft-bg)] [--btn-soft-hover:var(--button-destructive-soft-bg-hover)] [--btn-on-soft:var(--button-destructive-soft-fg)] [--btn-on-soft-hover:var(--button-destructive-soft-fg-hover)] [--btn-line:var(--destructive-soft-border)]',
+        success: 'bg-(--button-success-bg) text-(--button-success-fg) hover:bg-(--button-success-bg-hover) active:bg-(--button-success-bg-active) [--btn-fill:var(--button-success-bg)] [--btn-fill-hover:var(--button-success-bg-hover)] [--btn-on-fill:var(--button-success-fg)] [--btn-soft:var(--button-success-soft-bg)] [--btn-soft-hover:var(--button-success-soft-bg-hover)] [--btn-on-soft:var(--button-success-soft-fg)] [--btn-on-soft-hover:var(--button-success-soft-fg-hover)] [--btn-line:var(--success-soft-border)]',
+        warning: 'bg-(--button-warning-bg) text-(--button-warning-fg) hover:bg-(--button-warning-bg-hover) active:bg-(--button-warning-bg-active) [--btn-fill:var(--button-warning-bg)] [--btn-fill-hover:var(--button-warning-bg-hover)] [--btn-on-fill:var(--button-warning-fg)] [--btn-soft:var(--button-warning-soft-bg)] [--btn-soft-hover:var(--button-warning-soft-bg-hover)] [--btn-on-soft:var(--button-warning-soft-fg)] [--btn-on-soft-hover:var(--button-warning-soft-fg-hover)] [--btn-line:var(--warning-soft-border)]',
+        info: 'bg-(--button-info-bg) text-(--button-info-fg) hover:bg-(--button-info-bg-hover) active:bg-(--button-info-bg-active) [--btn-fill:var(--button-info-bg)] [--btn-fill-hover:var(--button-info-bg-hover)] [--btn-on-fill:var(--button-info-fg)] [--btn-soft:var(--button-info-soft-bg)] [--btn-soft-hover:var(--button-info-soft-bg-hover)] [--btn-on-soft:var(--button-info-soft-fg)] [--btn-on-soft-hover:var(--button-info-soft-fg-hover)] [--btn-line:var(--info-soft-border)]',
+        outline: 'border border-(--button-outline-border) bg-(--button-outline-bg) hover:bg-(--button-outline-bg-hover) hover:text-(--button-outline-fg-hover)',
+        ghost: 'bg-transparent hover:bg-(--button-ghost-bg-hover) hover:text-(--button-ghost-fg-hover)',
+        link: 'bg-transparent text-(--button-link-fg) underline-offset-4 hover:underline',
+      },
+      size: {
+        // Thang đo lấy đúng theo shadcn (đo trên ui.shadcn.com):
+        // xs 24px · sm 28px · default 32px · lg 36px, bo 8px cho hai cỡ nhỏ
+        // và 10px cho hai cỡ lớn. Nút chỉ có icon là ô vuông cùng chiều cao.
+        'xs': 'h-(--ui-control-height-xs) gap-(--button-gap-xs) rounded-(--button-radius-sm) px-(--ui-control-padding-x-xs) text-(length:--button-font-size-xs) [&_svg]:size-(--button-icon-size-xs)',
+        'sm': 'h-(--ui-control-height-sm) gap-(--button-gap-xs) rounded-(--button-radius-sm) px-(--ui-control-padding-x) text-(length:--button-font-size-sm)',
+        'default': 'h-(--ui-control-height-md) px-(--ui-control-padding-x)',
+        'lg': 'h-(--ui-control-height-lg) px-(--ui-control-padding-x)',
+        'icon-xs': 'size-(--ui-control-height-xs) rounded-(--button-radius-sm) [&_svg]:size-(--button-icon-size-xs)',
+        'icon-sm': 'size-(--ui-control-height-sm) rounded-(--button-radius-sm)',
+        'icon': 'size-(--ui-control-height-md)',
+        'icon-lg': 'size-(--ui-control-height-lg)',
+      },
+      tone: {
+        solid: '',
+        // KHÔNG cắt transition ở đây — xem `compoundVariants`. Trục này để rỗng
+        // vì `soft` chỉ có nghĩa với năm sắc có nhóm soft; đặt class ở tầng
+        // variant là áp cho cả chín, kể cả ba cái không có nhóm đó.
+        soft: '',
+      },
+
+      /**
+       * KIỂU TÔ — trục tách ra khỏi `variant`, theo mô hình Radix Themes.
+       *
+       * `variant` ở trên đang gộp hai thứ: sáu SẮC cộng ba KIỂU TÔ
+       * (`outline`/`ghost`/`link`). Vì vậy ô `outline × soft` không có định
+       * nghĩa, và trước đây nó im lặng không làm gì — xem mục cùng tên ở
+       * `CLAUDE.md`. Trục này đóng cái lỗ đó: sắc và kiểu tô không còn tranh
+       * nhau một prop.
+       *
+       * THÊM CHỨ KHÔNG ĐỔI. Ba giá trị cũ của `variant` giữ nguyên từng ký tự,
+       * và `fill` mặc định `solid` phát ra RỖNG — nên 456 chỗ gọi
+       * `variant="outline|ghost|link"` và 86 chỗ `tone="soft"` không phải sửa,
+       * và parity là chuyện cấu trúc chứ không phải lời hứa.
+       *
+       * Mỗi kiểu tô đọc BIẾN NGUỒN mà sáu sắc đặt ở trên, nên thêm một kiểu tô
+       * là **một dòng**, không phải 5 sắc × 4 token. Đó đúng là chỗ mô hình
+       * liệt kê tốn kém nhất.
+       *
+       * VIỀN CỦA `outline` VÀ CỦA `surface` KHÔNG cùng một token, và đó là
+       * phép đo chứ không phải thẩm mỹ. `surface` có nền nên viền chỉ là mép —
+       * `--x-soft-border` (tint 34%) hợp. `outline` KHÔNG có nền, nên viền
+       * chính là ranh giới của control và WCAG 1.4.11 đòi 3:1. Đo 100 tổ hợp
+       * (5 sắc × 5 bảng màu × sáng/tối × trên nền trang và trên card):
+       *
+       *   --x-soft-border      thấp nhất 1,22  — 50/100 trượt
+       *   --x (màu đặc)        thấp nhất 2,05  — 10/100 trượt
+       *   --x-soft-foreground  thấp nhất 5,32  — 0 trượt   <- chọn cái này
+       *
+       * Nó cũng chính là màu chữ của nút, nên viền và chữ cùng tông.
+       *
+       * Giá trị lui trong mỗi `var()` là bắt buộc, không phải phòng xa:
+       * `secondary` KHÔNG có nhóm soft ở bất kỳ tầng nào, nên thiếu nó thì
+       * `fill="soft"` trên secondary ra nền rỗng. Và ba variant cũ không đặt
+       * biến nào, nên chúng rơi về đúng token trung tính của chính chúng.
+       */
+      fill: {
+        solid: '',
+
+        soft: 'transition-[border-color,opacity,transform] bg-[var(--btn-soft,var(--btn-fill))] text-[var(--btn-on-soft,var(--btn-on-fill))] hover:bg-[var(--btn-soft-hover,var(--btn-fill-hover))] hover:text-[var(--btn-on-soft-hover,var(--btn-on-fill))]',
+
+        // Ô mà `outline × soft` lẽ ra phải là: nền pha loãng KÈM viền. Radix
+        // Themes gọi nó `surface`, nên lấy luôn cái tên thay vì bịa.
+        surface: 'transition-[border-color,opacity,transform] border bg-[var(--btn-soft,var(--btn-fill))] text-[var(--btn-on-soft,var(--btn-on-fill))] border-[var(--btn-line,var(--button-outline-border))] hover:bg-[var(--btn-soft-hover,var(--btn-fill-hover))] hover:text-[var(--btn-on-soft-hover,var(--btn-on-fill))]',
+
+        outline: 'border bg-transparent border-[var(--btn-on-soft,var(--button-outline-border))] text-[var(--btn-on-soft,inherit)] hover:bg-[var(--btn-soft,var(--button-outline-bg-hover))] hover:text-[var(--btn-on-soft,var(--button-outline-fg-hover))] active:bg-[var(--btn-soft,transparent)]',
+
+        ghost: 'bg-transparent text-[var(--btn-on-soft,inherit)] hover:bg-[var(--btn-soft,var(--button-ghost-bg-hover))] hover:text-[var(--btn-on-soft,var(--button-ghost-fg-hover))] active:bg-transparent',
+      },
+    },
+
+    // Nền pha loãng, chữ giữ nguyên sắc. Hover đậm thêm một nấc bằng token
+    // riêng — dùng `hover:bg-x/20` sẽ NHẠT ĐI ở chế độ tối, vì nền soft bản tối
+    // đã là 22%. Chỉ có cho các variant MÀU; outline/ghost/link vốn đã nhạt.
+    //
+    // `transition-[border-color,opacity,transform]` nằm Ở ĐÂY chứ không ở trục
+    // `tone`, và đó là một BẢN SỬA: nó bỏ `color` với `background-color` khỏi
+    // danh sách để chặn cú sập tương phản 1,09:1 giữa lúc soft chuyển sang nền
+    // đặc. Cú đó chỉ xảy ra với năm sắc dưới đây. Đặt ở tầng `tone` thì
+    // `outline`/`ghost` + `soft` cũng bị cắt — hai cái đó KHÔNG đổi diện mạo
+    // theo tone, nên chúng chỉ mất phần nội suy màu khi hover mà không được gì.
+    // Đo trước khi sửa: `outline` + `soft` ra `border-color, opacity, transform`
+    // thay vì đủ năm thuộc tính.
+    compoundVariants: [
+      { tone: 'soft', variant: 'default', class: 'transition-[border-color,opacity,transform] bg-(--button-default-soft-bg) text-(--button-default-soft-fg) hover:bg-(--button-default-soft-bg-hover) hover:text-(--button-default-soft-fg-hover)' },
+      { tone: 'soft', variant: 'destructive', class: 'transition-[border-color,opacity,transform] bg-(--button-destructive-soft-bg) text-(--button-destructive-soft-fg) hover:bg-(--button-destructive-soft-bg-hover) hover:text-(--button-destructive-soft-fg-hover)' },
+      { tone: 'soft', variant: 'success', class: 'transition-[border-color,opacity,transform] bg-(--button-success-soft-bg) text-(--button-success-soft-fg) hover:bg-(--button-success-soft-bg-hover) hover:text-(--button-success-soft-fg-hover)' },
+      { tone: 'soft', variant: 'warning', class: 'transition-[border-color,opacity,transform] bg-(--button-warning-soft-bg) text-(--button-warning-soft-fg) hover:bg-(--button-warning-soft-bg-hover) hover:text-(--button-warning-soft-fg-hover)' },
+      { tone: 'soft', variant: 'info', class: 'transition-[border-color,opacity,transform] bg-(--button-info-soft-bg) text-(--button-info-soft-fg) hover:bg-(--button-info-soft-bg-hover) hover:text-(--button-info-soft-fg-hover)' },
+    ],
+
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+      tone: 'solid',
+      fill: 'solid',
+    },
+  },
+)
+
+export type ButtonVariants = VariantProps<typeof buttonVariants>

package/src/variants/components/checkbox.ts

@@ -0,0 +1,67 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+/**
+ * Ô đánh dấu. Hai trục, đúng quy ước của repo:
+ *
+ * - `size` — `sm` 14px, `md` 16px (mặc định), `lg` 20px.
+ * - `tone` là **kiểu tô**: `outline` nền trong, `filled` nền xám khi chưa chọn.
+ *   PrimeVue gọi cái này là `variant="filled"`; ở đây `variant` dành riêng cho
+ *   **màu** (xem Button/Badge) nên phải đổi tên, không đổi ý nghĩa.
+ *
+ * Không có trục màu: một ô đánh dấu đã chọn luôn là màu primary. Trạng thái lỗi
+ * đi qua `invalid` chứ không phải qua `variant="destructive"` — nó là trạng thái
+ * xác thực, không phải một lựa chọn thiết kế.
+ */
+export const checkboxVariants = cva(
+  [
+    'peer inline-flex shrink-0 items-center justify-center border shadow-xs',
+    'transition-[color,background-color,border-color] duration-(--ui-control-duration)',
+    'focus-visible:outline-none',
+    'disabled:cursor-not-allowed disabled:opacity-50',
+    '[&_svg]:pointer-events-none [&_svg]:shrink-0',
+  ],
+  {
+    variants: {
+      // Bán kính bo theo cỡ: 4px trên ô 16px là tỉ lệ của bản gốc, giữ nguyên
+      // con số đó cho ô 14px thì trông tròn quá, cho ô 20px thì trông vuông quá.
+      size: {
+        sm: 'size-3.5 rounded-[3px] [&_svg]:size-3',
+        md: 'size-4 rounded-[4px] [&_svg]:size-3.5',
+        lg: 'size-5 rounded-[5px] [&_svg]:size-4',
+      },
+
+      tone: {
+        outline: 'bg-background',
+        filled: 'bg-muted',
+      },
+
+      /**
+       * Khai thành một trục của cva chứ không dùng `aria-invalid:` — lớp đã chọn
+       * và lớp lỗi cùng tô `background-color`, mà thứ tự thắng thua giữa hai
+       * variant của Tailwind do thứ tự trong stylesheet quyết định chứ không
+       * phải thứ tự mình viết. Gộp vào một nhánh thì không còn gì để đoán.
+       */
+      invalid: {
+        false: [
+          'border-input focus-visible:shadow-focus',
+          'data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground',
+          'data-[state=indeterminate]:border-primary data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground',
+        ],
+        true: [
+          'border-destructive focus-visible:shadow-focus-invalid',
+          'data-[state=checked]:bg-destructive data-[state=checked]:text-destructive-foreground',
+          'data-[state=indeterminate]:bg-destructive data-[state=indeterminate]:text-destructive-foreground',
+        ],
+      },
+    },
+
+    defaultVariants: {
+      size: 'md',
+      tone: 'outline',
+      invalid: false,
+    },
+  },
+)
+
+export type CheckboxVariants = VariantProps<typeof checkboxVariants>

package/src/variants/components/chip.ts

@@ -0,0 +1,51 @@
+import type { VariantProps } from 'class-variance-authority'
+import { cva } from 'class-variance-authority'
+
+/**
+ * Chip là Badge **tương tác được**: gỡ được, cao hơn, bo tròn hẳn.
+ *
+ * Bảng này KHÔNG tham chiếu `badgeVariants` — nó chỉ khai hình dáng, còn trục
+ * màu (`variant`/`tone`) thì bên gọi lấy thẳng từ `badgeVariants` rồi ghép lại
+ * bằng `cn()`. Bốn chỗ đang làm vậy: `Chip`, `InputTagsItem` và hai bản Select.
+ *
+ * Khác biệt thật giữa Badge và Chip là **ngữ nghĩa**: Badge là nhãn tĩnh, Chip
+ * là một mục người dùng thêm vào rồi bỏ ra (bộ lọc đang áp, người nhận trong ô
+ * "To:").
+ *
+ * Từ vựng cỡ ở đây — `sm` / `default` / `lg` — khớp `buttonVariants` và
+ * `badgeVariants`; ba bảng nói chung một từ vựng.
+ */
+export const chipVariants = cva(
+  'inline-flex max-w-full items-center gap-1.5 rounded-full border font-medium whitespace-nowrap',
+  {
+    variants: {
+      size: {
+        // Giãn dòng phải khai TƯỜNG MINH bên cạnh mọi `text-[Npx]`: cỡ chữ tuỳ ý
+        // chỉ đặt `font-size`, nên line box rơi lui về giá trị thừa kế và chữ lệch
+        // trong một hộp CAO CỐ ĐỊNH. Cùng lỗi đã đo ở `badge.ts` — xem ghi chú ở đó.
+        sm: 'h-5 gap-1 pl-2 pr-1 text-[11px] leading-none [&_svg]:size-3',
+        default: 'h-6 pl-2.5 pr-1 text-xs [&_svg]:size-3.5',
+        lg: 'h-7 pl-3 pr-1.5 text-[13px] leading-none [&_svg]:size-4',
+      },
+
+      /** Không có nút gỡ thì phần đệm phải cân lại hai bên. */
+      removable: {
+        true: '',
+        false: '',
+      },
+    },
+
+    compoundVariants: [
+      { removable: false, size: 'sm', class: 'pr-2' },
+      { removable: false, size: 'default', class: 'pr-2.5' },
+      { removable: false, size: 'lg', class: 'pr-3' },
+    ],
+
+    defaultVariants: {
+      size: 'default',
+      removable: false,
+    },
+  },
+)
+
+export type ChipVariants = VariantProps<typeof chipVariants>