Tuỳ biến style

<Button className="rounded-circular px-5">Bo tròn</Button>
<Button appearance="primary" className="min-w-40">Rộng hơn</Button>
<Badge className="tracking-wide uppercase">Mới</Badge>

cn() trong src/lib/cn.ts là clsx + tailwind-merge đã được dạy scale của Yugen. Thiếu bước này, tailwind-merge gốc coi text-body1 là một màu chữ và xoá nó khi gặp text-foreground-1 — chữ sẽ rơi về cỡ mặc định. Kết quả thật của cn() trên trang này:

Spacing

Spacing dùng thang số của Tailwind: p-3, gap-2, mt-6. Mười bậc dưới đây trùng ramp spacing của Fluent, nên khi chuyển từ Fluent UI chỉ cần đổi tên: spacingHorizontalM → px-3. Padding, margin và gap nên nằm trong mười bậc này; kích thước phần tử (h-8, size-5, w-64) dùng các số còn lại.

Alias viết hoa cũ (p-M, gap-SNudge) vẫn chạy nhưng đã deprecated từ 0.10 và sẽ bị bỏ ở 1.0. Đổi theo cột bên phải của bảng.

Vì mã nguồn nằm trong dự án, cách “chuẩn shadcn” là sửa thẳng bảng variants trong Button.tsx. Khi muốn giữ file gốc nguyên vẹn để dễ cập nhật, hãy bọc component và thêm variant bằng cva:

import { cva, type VariantProps } from "class-variance-authority";
import { Button, type ButtonProps } from "@/components/ui";
import { cn } from "@/lib/cn";

const pillVariants = cva("rounded-circular", {
  variants: {
    tone: {
      neutral: "",
      brand:
        "border-transparent bg-brand-background-2 text-brand-foreground-2 hover:bg-brand-background-2-hover active:bg-brand-background-2-pressed",
    },
  },
  defaultVariants: { tone: "neutral" },
});

type PillButtonProps = ButtonProps & VariantProps<typeof pillVariants>;

export function PillButton({ tone, className, ...props }: PillButtonProps) {
  return <Button className={cn(pillVariants({ tone }), className)} {...props} />;
}

<PillButton>Neutral</PillButton>
<PillButton tone="brand" icon={<Star20Regular />}>Đã gắn sao</PillButton>

Các component cũng export hàm variant để áp style lên phần tử khác: buttonVariants, linkVariants, imageVariants, toggleButtonVariants. Ví dụ <a className={buttonVariants({ appearance: "primary" })}> — tuy vậy <Button asChild> thường gọn hơn (xem trang Slot).

<MenuTrigger asChild>
  <Button
    appearance="subtle"
    icon={<ChevronDown20Regular className="transition-transform duration-normal" />}
    iconPosition="after"
    className="data-[state=open]:bg-subtle-pressed data-[state=open]:text-foreground-1 data-[state=open]:[&_svg]:rotate-180"
  >
    Sắp xếp
  </Button>
</MenuTrigger>

{/* Button medium đặt [&_svg]:size-5 — muốn icon 16px phải dùng hậu tố ! (Tailwind v4) */}
<Button icon={<Star20Regular className="size-4!" />}>Icon 16px trong nút medium</Button>

Hậu tố ! (cú pháp Tailwind v4, đặt ở cuối class) chỉ dùng khi component cha đặt selector có độ ưu tiên cao hơn như [&_svg]:size-5. Đừng rải ! để thắng className của chính component — className của bạn đã đứng cuối cn().

Ví dụ: một ô chỉ đọc tự viết nhưng vẫn có đáy stroke-accessible và thanh brand khi focus (bấm vào hoặc Tab tới ô):

import { fieldControlClass } from "@/components/ui";
import { cn } from "@/lib/cn";

<div
  tabIndex={0}
  role="textbox"
  aria-readonly
  aria-label="Mã giới thiệu"
  className={cn(fieldControlClass, "flex h-8 w-64 items-center px-2.5 font-mono text-body1")}
>
  YUGEN-2026-SAKURA
</div>

npx @yugen-ui/cli@latest css

Lệnh ghi yugen-ui.css cạnh file CSS chính và thay @import "yugen-ui/theme.css" bằng @import "./yugen-ui.css". yugen init làm sẵn bước này cho dự án mới.

/* src/yugen-ui.css, do yugen css ghi */
@import "yugen-ui/theme-core.css";
/* Một dòng cho mỗi thư mục component mà mã import. */
@import "yugen-ui/sources/Button.css";
@import "yugen-ui/sources/DataGrid.css";
@import "yugen-ui/sources/Dialog.css";
@import "yugen-ui/sources/YugenProvider.css";

• CSS gzip, gồm cả class của chính app, đo bằng scripts/measure-css.mjs.
• Import thêm component thì chạy lại lệnh (ở chế độ package, yugen add tự làm), hoặc đặt nó trong script predev / prebuild. yugen css --check thoát với mã 1 khi file đã cũ, yugen doctor cũng cảnh báo. Xem trang CLI.
• Mỗi file đã gồm các component mà component đó dùng bên trong (SplitButton.css có Menu và Button), nên chỉ cần liệt kê component bạn import.
• Tên file là thư mục chứa component: NavItem ở sources/Nav.css, toast ở sources/Toast.css. Bảng export → file nằm trong yugen-ui/sources/index.json. Có thể tự viết các dòng này thay cho CLI.
• Thiếu một file thì component đó không có style. import * as, export * hay import("yugen-ui") có thể dùng mọi component, nên khi gặp chúng file sinh ra quay về theme.css.
• Không dùng Tailwind: yugen css --precompile biên dịch cùng danh sách thành CSS thường để thay styles.css.
• Copy mã nguồn component (shadcn registry, @yugen-ui/cli add) thì không cần: Tailwind đã quét thư mục của app. styles.css (không dùng Tailwind) luôn chứa mọi component.

<div className="flex items-center gap-3">
  <Avatar name="Trần Minh Anh" color="colorful" size={40} />
  <div className="min-w-0 flex-1">
    <p className="truncate text-body1 font-semibold text-foreground-1">Trần Minh Anh</p>
    <p className="truncate text-caption1 text-foreground-3">Thiết kế sản phẩm · Nhóm Nền tảng…</p>
  </div>
  <div className="flex shrink-0 items-center gap-1">
    <Button size="small">Nhắn tin</Button>
    <Button size="small" appearance="subtle" icon={<MoreHorizontal20Regular />} aria-label="Thêm thao tác" />
  </div>
</div>

• min-w-0 flex-1 trên khối chữ: flex item mặc định không co nhỏ hơn nội dung, thiếu min-w-0 thì truncate không có tác dụng và hàng bị tràn.
• shrink-0 trên avatar và nhóm thao tác để chúng giữ nguyên kích thước khi chữ dài.
• gap-* thay cho margin — tự đúng khi đổi sang RTL. CardHeader, ListItem, TableCellLayout và Persona đã đóng gói sẵn công thức này.