Nền tảng
Màu
Đã đặc tảBa tầng, sáu mươi ba vai trò semantic mỗi theme. Interaction Blue sở hữu hành động; màu thương hiệu sở hữu nhận diện. Control dùng border.control, vật trang trí dùng border.subtle.
Cấu trúc
Ba tầng, và vì sao tầng dưới là riêng tư
| Tầng | Ví dụ tên | Ai bind | Đổi theo theme |
|---|---|---|---|
| Foundation ramp | --nf-foundation-color-neutral-*, -jade-*, -cobalt-*, -coral-*, -utility-* | không ai trong giao diện sản phẩm | không |
| Semantic | --nf-semantic-surface-*, -text-*, -border-*, -action-*, -focus-*, -brand-*, -status-* | màn hình, layout, trang tài liệu | có |
| Component alias | --nf-component-button-*, -field-*, -card-*, -overlay-*, -channelMark-* | primitive trong @nexobox/ui | có, qua semantic |
Ramp là riêng tư vì một ramp là một thang, không phải một ý định. Nhóm utility không đánh bậc là một bất thường có hệ quả thật: không có ramp đánh số cho trạng thái, chỉ có các thành viên phẳng utility.<kind>{Light,Dark}{Bg,Fg,Border}.
Token
Sáu mươi ba vai trò semantic
Mỗi chip đọc màu thật của nó lúc chạy qua getComputedStyle, theo theme đang mở trên trang này.
surface — 6
canvas
Unknownbase
Unknownraised
Unknownsubtle
Unknownhover
Unknownpressed
Unknowntext — 4
primary
Unknownsecondary
Unknownmuted
Unknownlink
Unknownborder — 4
subtle
Unknowncontrol
Unknownstrong
Unknowndivider
Unknownaction — 14
primary-background
Unknownprimary-border
Unknownprimary-foreground
Unknownprimary-hover
Unknownprimary-pressed
Unknowndanger-background
Unknowndanger-border
Unknowndanger-foreground
Unknowndanger-hover
Unknowndanger-pressed
Unknownselected-background
Unknownselected-foreground
Unknowndisabled-background
Unknowndisabled-foreground
Unknownfocus — 1
ring
Unknownbrand — 9
accent
UnknownonAccent
Unknownsoft
UnknownonSoft
UnknownsoftBorder
Unknownpalette.1
Unknownpalette.2
Unknownpalette.3
Unknownpalette.4
Unknownstatus — 25
danger.background
Unknowndanger.border
Unknowndanger.border-subtle
Unknowndanger.foreground
Unknowndanger.icon
Unknowninformation.background
Unknowninformation.border
Unknowninformation.border-subtle
Unknowninformation.foreground
Unknowninformation.icon
Unknownneutral.background
Unknownneutral.border
Unknownneutral.border-subtle
Unknownneutral.foreground
Unknownneutral.icon
Unknownsuccess.background
Unknownsuccess.border
Unknownsuccess.border-subtle
Unknownsuccess.foreground
Unknownsuccess.icon
Unknownwarning.background
Unknownwarning.border
Unknownwarning.border-subtle
Unknownwarning.foreground
Unknownwarning.icon
UnknownTương tác
Interaction Blue — một ngôn ngữ hành động
semantic.brand.* giữ màu riêng của từng sản phẩm. semantic.action.primary.*, action.selected.*, text.link và focus.ring dùng cùng ramp cobalt trên cả năm sản phẩm. Light dùng cobalt 600 với chữ trắng; dark dùng cobalt 300 với chữ cobalt 950.
Thông tin
Cobalt có nghĩa “tương tác”; màu thương hiệu có nghĩa “nhận diện”. Secondary, Outline và Ghost vẫn trung tính khi nghỉ. Danger, status, disabled, Nexi và channel mark không đổi.
Luật viền
Luật viền — control so với trang trí
Một phần tử là control — người dùng nhấn, gõ, chọn được — thì viền của nó dùng border.control. Một phần tử là trang trí — thẻ, chip, đường phân cách — thì dùng border.subtle. WCAG 2.2 SC 1.4.11 đòi 3:1 khi viền là ranh giới duy nhất của một thành phần giao diện.
Ví dụ dạy luật: viền nút secondary trên nền của chính nó. Ngày 2026-09-23 cặp này đổi từ border.subtle sang border.control và bây giờ đạt.
Viền nút secondary / nền nút secondary
UnknownTheme
Theme sản phẩm
Selector là thuần attribute: [data-nexo-product][data-nexo-mode], không gắn html. Một scope theme lồng nhau hoạt động trên bất kỳ phần tử, nhưng selector đòi cả hai attribute cùng lúc — một phần tử chỉ đặt data-nexo-mode không khớp gì cả và im lặng dùng theme của tổ tiên. Theme không phải tenant: ?product= và ?mode= trên trang tài liệu là điều khiển specimen.
Khoảng trống
Nhóm inverse — một khoảng trống đang mở
Cảnh báo
semantic.inverse được khai trong nexocrew-light, nexocrm-light và nexocrm-dark. Bảy theme còn lại kế thừa màu của NexoCrew từ khối :rootthay vì có màu nghịch đảo của riêng mình — panel kể chuyện của auth shell mang xanh jade của NexoCrew trên mọi sản phẩm. Đây là W7.7, trạng thái blocked: trên nền tối, "nghịch đảo" có thể là một panel sáng, và đó là một quyết định thiết kế, không phải một phép tính.
Quy tắc
Do / Don't
| Do | Don't | Vì sao |
|---|---|---|
| Bind --nf-semantic-* và --nf-component-* | Bind --nf-foundation-color-* trong giao diện sản phẩm | Ramp không mang ý định; bind vào nó là chôn ý định vào caller |
| Dùng border.control cho mọi thứ nhấn được | Chọn viền bằng mắt | 1.4.11 là ngưỡng, không phải gợi ý |
| Để icon thừa hưởng currentColor | Cho icon một token màu riêng | Icon không có token màu và không nên có |
| Dùng status.<kind>.icon cho màu icon trạng thái | Tô nền theo trạng thái để truyền trạng thái | Trạng thái đi bằng icon, không bằng nền tô |
| Dùng Interaction Blue qua action / text.link / focus | Dùng brand.accent làm màu control | Nhận diện và hành vi là hai ý định khác nhau theo DS-020 |
| Thêm màu mới bằng cách thêm token ở nguồn DTCG | Gõ hex vào class hay CSS | check-auth-tokens.mjs bắt hex; một hex là màu không ai đổi được theo theme |
| Nói Unknown khi một vai trò chưa được quyết | Chọn một bậc ramp gần đúng để tạm | Một giá trị tạm không có ngày hết hạn và sẽ ship |
Chưa quyết
Open questions
| Question | Owner | Resolves when |
|---|---|---|
| surface.base và surface.raised bằng nhau ở cả năm theme light, chênh 1,21:1 ở dark. Hệ thống có ý định biểu đạt độ nổi bằng màu nền không? | nexoboxvn@gmail.com | N04 phân xử. Đổi giá trị sẽ đổi mọi thẻ trong sản phẩm |
| Bảy theme còn lại lấy bảng màu nghịch đảo ở đâu? | nexoboxvn@gmail.com | W7.7. Trên nền tối, nghịch đảo có thể là panel sáng — một quyết định |