Component
Token
Pill đặt tên một design token hoặc một giá trị máy ngắn khác (color-accent, spacing-md). Cặp hue mềm, pink theo mặc định, để nó đọc như một giá trị chứ không phải trạng thái. Một phần tử đầu tùy chọn: icon 12px, swatch 12px hiện một color token ở mode đang dùng, hoặc Avatar 16px cho một người hoặc một nhóm. Khi có onRemove, pill kết thúc bằng button xóa, cho các giá trị đã chọn mà người dùng có thể bỏ ra.
Xem trước
import { Token } from "@/components/ui/token"
<Token>spacing-md</Token>Cách dùng
Khi nào dùng
- Hiện tên design token hoặc một giá trị máy ngắn khác, trong table hoặc trong đoạn văn.
- Hiện màu của một color token bằng swatch cạnh tên.
- Hiện các giá trị người dùng đã chọn và có thể bỏ ra lại, chẳng hạn bộ lọc đang bật, với onRemove.
Khi nào không dùng
- Trạng thái hoặc danh mục. Dùng Badge.
- Như button hoặc link riêng. Để token sao chép được, bọc nó trong một button và đặt label cho button.
Biến thể
color
Cặp mềm: background-<hue> với text-<hue>. Không bao giờ là solid. pink là mặc định để token tách khỏi badge trạng thái.
import { Token } from "@/components/ui/token"
<Token>spacing-md</Token>
<Token color="red">spacing-md</Token>
<Token color="orange">spacing-md</Token>
<Token color="yellow">spacing-md</Token>
<Token color="green">spacing-md</Token>
<Token color="teal">spacing-md</Token>
<Token color="blue">spacing-md</Token>
<Token color="purple">spacing-md</Token>
<Token color="gray">spacing-md</Token>Ví dụ
Mặc định
import { Token } from "@/components/ui/token"
<Token>spacing-md</Token>Token màu
Swatch đọc token, nên nó đổi theo mode.
import { Token } from "@/components/ui/token"
<Token swatch="var(--color-accent)">color-accent</Token>Có icon
import { IconRuler } from "@tabler/icons-react"
import { Token } from "@/components/ui/token"
<Token>
<IconRuler size={12} />
size-element-md
</Token>Có thể xóa
Một giá trị đã chọn mà người dùng có thể bỏ ra. removeLabel đặt tên button kèm value.
import { Token } from "@/components/ui/token"
<Token color="blue" onRemove={removeToken} removeLabel="Gỡ font-size-md">font-size-md</Token>Có avatar
Một người nhận mà người dùng đã chọn. Token nêu tên người, nên alt của avatar để trống.
import { Avatar } from "@/components/ui/avatar"
import { Token } from "@/components/ui/token"
<Token color="gray" avatar={<Avatar variant="solid" color="blue" alt="">A</Avatar>} onRemove={removeToken} removeLabel="Gỡ ada@example.com">ada@example.com</Token>Nên và không nên
Nên
- Dùng ở mọi chỗ docs hoặc UI hiện tên token, trong table và trong đoạn văn.
- Thêm swatch cho color token, trỏ tới chính token đó: swatch="var(--color-accent)".
- Giữ label đúng như viết trong code.
- Cho token có thể xóa một removeLabel có value: Xóa spacing-md.
- Với giá trị là một người hoặc một nhóm, mở đầu bằng Avatar solid và một chữ cái đầu.
Không nên
- Đừng dùng cho trạng thái hoặc danh mục; đó là Badge.
- Đừng đặt hơn một phần tử đầu (icon, swatch hoặc avatar) trong cùng một token.
- Đừng dùng như button hoặc link riêng.
- Đừng làm token có thể xóa khi người dùng không thêm lại được; việc xóa phải là thứ họ có thể hoàn tác.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| color | enum | pink | red | orange | yellow | green | teal | blue | purple | gray | pink | Cặp mềm: background-<hue> với text-<hue>. Không bao giờ là solid. pink là mặc định để token tách khỏi badge trạng thái. |
| swatch | string | - | - | Màu CSS cho swatch đầu, thường là var(--color-<token>) để theo light và dark. Bỏ qua với token không phải màu. |
| avatar | node | - | - | Một Avatar solid trước label, cho giá trị là một người hoặc một nhóm, chẳng hạn người nhận: <Avatar variant="solid" color="blue" alt="">A</Avatar>. Một chữ cái đầu; token đặt size của nó. |
| onRemove | function | - | - | Được gọi khi button xóa được nhấn. Đặt prop này thì hiện button. Dùng cho giá trị người dùng đã chọn và có thể bỏ ra lại, chẳng hạn bộ lọc hoặc các value của field nhiều value. |
| removeLabel | string | - | - | Tên truy cập của button xóa, có value trong đó: Xóa spacing-md. Bắt buộc khi có onRemove. |
Slot
| Tên | Bắt buộc | Mô tả |
|---|---|---|
| label | có | Tên token hoặc value, đúng như viết trong code. |
| icon | không | Icon đầu tùy chọn. Dùng icon hoặc swatch, không dùng cả hai. |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Pill: nền hue mềm, radius-full, chữ gọn, cao 20px. Chữ trong đoạn có Token dùng leading-5. |
| icon | Icon Tabler tùy chọn trước label, 12px. |
| swatch | Vòng tròn 12px tùy chọn, tô bằng màu của token, với mép border-strong. |
| avatar | Avatar tùy chọn trước label, vẽ ở 16px với chữ cái đầu 12px và kéo vào padding của pill, để token vẫn cao 20px. Solid, vì nền mềm sẽ không nổi trên pill. |
| remove | Button xóa tùy chọn ở cuối: vòng tròn 16px quanh X 12px theo hue của token. Overlay hover và pressed trung tính, focus ring. |
| hitArea | ::before trong suốt, căn giữa button xóa, không bao giờ nhỏ hơn size-target-min (24px trên chuột, 44px trên cảm ứng). |
Khả năng truy cập
Role: generic
| Phím | Hành động |
|---|---|
| Tab | Khi có onRemove: chuyển focus tới button xóa và hiện focus ring. |
| Enter, Space | Khi có onRemove: xóa token. |
- Bản thân Token không tương tác. Để token sao chép được, bọc nó trong một button và đặt label cho button.
- Button xóa là button thật, được removeLabel đặt tên, và tên phải gồm value (Xóa spacing-md), vì một trang thường có vài token. Type bắt buộc removeLabel khi có onRemove.
- Sau khi xóa, chuyển focus tới button xóa của token tiếp theo hoặc về field mà các token thuộc về, để focus không mất cùng button.
- Button xóa cao 16px nhưng vùng nhấn là size-target-min (24px trên chuột, 44px trên cảm ứng).
- Avatar đầu bị ẩn với trình đọc màn hình (aria-hidden), vì label đã nêu tên người.
- Swatch và icon chỉ để trang trí (aria-hidden). Chữ là tên token, nên nghĩa không bao giờ phụ thuộc vào màu.
- Chữ vẫn chọn được, nên người đọc có thể sao chép tên token.
Cài đặt
npx werewolf-ui add tokenChạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.