Giao diện

Orbz có hai chế độ giao diện loại trừ nhau:

chọn một preset tích hợp; hoặc
bỏ preset và cung cấp bất kỳ thuộc tính nào trong năm thuộc tính color-*.

Không có thuộc tính palette. Tên công khai là preset.

Preset tích hợp

Preset	Màu chính	Màu phụ	Điểm nhấn	Vùng sáng	Lõi
`neongate` (mặc định)	`#6C5CFF`	`#00E9FF`	`#FF4DDE`	`#FFB07A`	`#14142B`
`periwinkle`	`#6667AB`	`#8FB8FF`	`#E66FA9`	`#F3ECFF`	`#111226`
`magenta`	`#BB2649`	`#F06A82`	`#29B8A6`	`#FFDCE4`	`#250A12`
`peach`	`#FFBE98`	`#FF8F70`	`#D987A3`	`#FFF0E7`	`#2A1516`
`mocha`	`#A47864`	`#D3A17E`	`#7FA18F`	`#F2E2D7`	`#211613`
`ivory`	`#F0EEE9`	`#AFC7D3`	`#C8B3D4`	`#FFFFFF`	`#171A20`


<orb-z preset="periwinkle"></orb-z>

Neongate vẫn là giao diện mặc định khi thiếu preset, nên chế độ tùy chỉnh kế thừa màu Neongate cho các giá trị chưa cung cấp.

Dùng tên và giá trị được export khi xây dựng bộ chọn:


import {
  DEFAULT_ORBZ_PRESET,
  ORBZ_PRESET_NAMES,
  ORBZ_PRESETS,
  type OrbzPresetName,
} from "@neongate-ai/orbz";
 
function getPreview(name: OrbzPresetName) {
  return ORBZ_PRESETS[name];
}
 
const NeongateColors = getPreview(DEFAULT_ORBZ_PRESET);

Tên preset Neongate

Preset mang tên Neongate (neongate), độc lập với tài khoản GitHub lưu Orbz. Bản 1.0.1 vô tình công bố khóa API dựa trên tên tài khoản; bản 1.0.2 khôi phục neongate mà không đổi màu. Tài liệu này dùng gói đã phát hành @neongate-ai/orbz@1.0.2.

DEFAULT_ORBZ_PRESET và getter preset mặc định trả về neongate. Dùng tên chuẩn trong mã đánh dấu tường minh mới:


<orb-z preset="neongate"></orb-z>

Tên cũ dựa trên tài khoản vẫn được thuộc tính, kiểu và guard chấp nhận, nhưng được chuẩn hóa thành neongate, kể cả thuộc tính phản ánh và getter. transformOrbzConfiguration() chuẩn hóa cấu hình rút gọn hoặc đầy đủ dùng tên cũ mà không sửa đầu vào.

ORBZ_PRESET_NAMES liệt kê sáu tên chuẩn. Khóa cũ là bí danh bất biến, không liệt kê được của ORBZ_PRESETS.neongate, nên đọc trực tiếp vẫn hoạt động mà không tạo lựa chọn thứ bảy. Để theo mặc định của gói, ưu tiên DEFAULT_ORBZ_PRESET và ORBZ_PRESETS[DEFAULT_ORBZ_PRESET]. Trong HTML mặc định, bỏ preset:


<orb-z></orb-z>

Bỏ preset cũng cho phép màu tùy chỉnh có hiệu lực. Tạo lựa chọn từ ORBZ_PRESET_NAMES của gói đã cài và đọc ghi chú bản 1.0.2 khi nâng cấp từ 1.0.1.

Bảng màu tùy chỉnh

Xóa hoặc bỏ preset, rồi đặt một hay nhiều màu CSS hợp lệ:


<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

Thuộc tính	Vai trò
`color-primary`	Màu vùng chủ đạo
`color-secondary`	Màu vùng tương phản và vòng
`color-accent`	Hào quang và năng lượng bổ trợ
`color-highlight`	Vùng sáng ấm hoặc rực
`color-background`	Màu lõi quả cầu

Có thể chỉ tùy chỉnh một phần màu. Giá trị còn thiếu kế thừa Neongate mặc định, nên chỉ đổi một màu cũng hợp lệ:


<orb-z color-accent="#FF6B35"></orb-z>

Preset ưu tiên khi xung đột

Không cung cấp đồng thời preset và màu tùy chỉnh. Nếu cùng tồn tại khi chạy, Orbz áp dụng preset, bỏ qua màu tùy chỉnh và ghi lỗi console liệt kê thuộc tính xung đột.


<!-- Invalid: preset wins and color-primary is ignored. -->
<orb-z preset="mocha" color-primary="#7C3AED"></orb-z>

Các thuộc tính tùy chỉnh vẫn ở phần tử chủ và có hiệu lực khi xóa preset. Vì vậy trình chỉnh sửa màu nên chuyển chế độ tường minh:


const orb = document.querySelector("orb-z");
 
orb?.removeAttribute("preset");
orb?.setAttribute("color-primary", "#7C3AED");

Quy tắc áp dụng cho mọi framework vì đều ghi cùng thuộc tính gốc. Xóa preset trước khi ghi màu tùy chỉnh.

Kích thước và độ nổi

size điều khiển cả chiều rộng và chiều cao. Trong HTML, truyền độ dài CSS. Trong thuộc tính JavaScript, số dương được hiểu là pixel.


<orb-z size="18rem" elevated></orb-z>

elevated thêm bóng tròn căn giữa quanh quả cầu. Đây là thuộc tính boolean chuẩn: có mặt là đúng, kể cả elevated="false". Để tắt, xóa thuộc tính HTML hoặc gán false cho thuộc tính JavaScript.

Những phần chủ ý không cho tùy chỉnh

Biến CSS, selector, lớp và phần Shadow DOM nội bộ là riêng tư, không phải API chủ đề được hỗ trợ. Thuộc tính được ghi trong tài liệu là hợp đồng ổn định, giữ giao diện nhất quán giữa framework và cho phép cải tiến kết xuất nội bộ.