Component / 050 / NEXOFRAME

StatCard

Mẫu chuẩn

Một thẻ gồm một con số lớn, một nhãn nói con số đó là gì, một dòng chú thích về phạm vi và một icon trong ô màu theo tone. Nó dựng trên Card và không báo giá trị nào ra ngoài. Tone ai dùng overlay Nexi Lens V2, thay cho màu tím kit viết cứng.

Composite tầng 2Dựng từ Card4 tone2-4 thẻ mỗi dải

Playground

Đổi brand, theme và tone để xem ô icon đổi màu, và tone "ai" bọc trong overlay Nexi.

Nhân sự sẵn sàng

trong 4 Human AI

Tone hiện tại: "brand".

import { StatCard } from "@nexobox/ui";
import { UserGroupIcon } from "@nexobox/ui/icons/UserGroupIcon";

<StatCard
  label="Nhân sự sẵn sàng"
  value="3"
  caption="trong 4 Human AI"
  icon={UserGroupIcon}
  tone="brand"
/>

Bài toán

Người quản lý mở trang Tổng quan để biết trong vài giây đội ngũ có ổn không. Mỗi con số cần nhãn và phạm vi, nếu không "3" chẳng nói gì. Card cho khung nhưng không cho thứ bậc chữ giữa con số, nhãn và chú thích, cũng không cho ô icon theo tone. Ghép tay ở mỗi trang thì bốn thẻ sẽ lệch nhau.

Khi nào sử dụng

Nên dùng

Một chỉ số tổng hợp, kèm nhãn và phạm vi. Dải từ 2 đến 4 thẻ ở đầu trang tổng quan.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Nhiều cặp nhãn–giá trị về một đối tượng	DescriptionList
Số đếm cạnh tiêu đề khối	SectionHeader (`count`)
Chuỗi thời gian	Biểu đồ. `kpi-card.tsx` của dashboard có thể bọc StatCard và thêm sparkline, nhưng sparkline không thuộc composite này
Trạng thái của một mục	Badge hoặc StatusDot

Dựng từ

Primitive tầng 1	Vai trong composite
Card	Khung, viền, bán kính, đệm.

StatCard thêm gì
Thứ bậc chữ: con số (`heading1`), nhãn (`ui`), chú thích (`caption`)
Ô icon theo tone: `brand`, `information`, `warning`, `ai`
Tone `ai` bọc ô icon trong `data-nexi-v2`, để `brand-*` đổi sang iris của Nexi

Anatomy

Khối chữ (nhãn, con số, chú thích) và ô icon là hai nhánh của một hàng Card, giãn cách bằng justify-between — ô icon không nằm trong khối chữ.

Variants

Tone	Nền ô icon	Màu icon
`brand` (mặc định)	`brand-soft`	`brand-accent`
`information`	`status-information-background`	`status-information-icon`
`warning`	`status-warning-background`	`status-warning-icon`
`ai`	`brand-soft` trong `[data-nexi-v2]`	`brand-accent` trong `[data-nexi-v2]`

States

Một trạng thái hiển thị. Không nhận tương tác. Khi đang tải, host render Skeleton thay cho thẻ. Composite không có trạng thái tải riêng.

Bàn phím & trợ năng

Không nhận tiêu điểm, không thêm phím.

Con số và nhãn đọc theo thứ tự DOM: nhãn trước, con số sau, rồi chú thích -- để trình đọc màn hình không đọc một con số trơ trọi.

Seam — host sở hữu gì

Composite không tính số, không định dạng số, không điều hướng.

Host sở hữu	Cấp qua
Con số đã định dạng	`value`
Nhãn, chú thích, icon	`label`, `caption`, `icon`

API & triển khai

Prop	Mặc định	Quy ước
label	—	Bắt buộc.
value	—	Bắt buộc. Đã định dạng.
caption	undefined	Phạm vi của con số.
icon	undefined	Hugeicons icon, qua Icon của @nexobox/ui.
tone	"brand"	"brand" \| "information" \| "warning" \| "ai".

Design tokens

--nf-semantic-brand-soft, --nf-semantic-brand-accent, --nf-semantic-status-information-background, --nf-semantic-status-information-icon, --nf-semantic-status-warning-background, --nf-semantic-status-warning-icon, --nf-foundation-typography-heading1-*, --nf-foundation-typography-ui-*, --nf-foundation-typography-caption-*, --nf-semantic-text-primary, --nf-semantic-text-secondary, --nf-semantic-text-muted, --nf-foundation-radius-control (ô icon), --nf-foundation-size-icon, --nf-foundation-space-2, --nf-foundation-space-3. Qua Card: --nf-component-card-*.

Do / Don't

Nên dùng

Chú thích nói phạm vi: "trong 4 Human AI". Tone ai cho chỉ số do Nexi tạo ra. 2–4 thẻ mỗi dải.

Tránh dùng

Con số không có phạm vi. Viết màu tím trực tiếp — tím là màu của Nexi và chỉ đến qua overlay. Tám thẻ ngang nhau: không cái nào còn nổi bật.