@quorix/ui

v2.1.8

Published

8 days ago

Design System for Quorix Vietnam

0High
0Medium
0Low

@quorix/ui cung cấp một giải pháp toàn diện, cực nhẹ và không phụ thuộc (zero-dependency) để xây dựng các giao diện người dùng hiện đại. Được phát triển riêng cho hệ sinh thái của Quorix Vietnam, bộ khung này là sự giao thoa hoàn hảo giữa tính thẩm mỹ cao cấp và các tiêu chuẩn kỹ thuật khắt khe.

👀 Trải nghiệm Demo & Showcase: Xem bản Visualization chính thức của Quorix UI

📢 v2.1.8: Đã bổ sung article extensions, primitive AI search/chat, typed package exports và tabs ARIA được harden.

✨ Tại sao nên chọn Quorix UI?

Zero Dependencies: Lõi TypeScript được viết tự thân hoàn toàn. Chúng tôi đảm bảo hiệu suất tối ưu và loại trừ rủi ro (side-effects) từ các thư viện bên thứ ba.
Thiết kế hiện đại (High-end Aesthetics): Ứng dụng khéo léo phong cách thiết kế Glassmorphism kết hợp hệ thống phân lớp Spatial tạo cảm giác có chiều sâu và cao cấp.
Tích hợp Icons tối ưu: Tích hợp mượt mà với Lucide Icons. Sử dụng thuộc tính CSS currentColor để các icon tự động đồng bộ màu sắc theo ngữ cảnh mà không làm nặng tiến trình render.
Tree-shakeable Exports: Được build sẵn bằng esbuild, hỗ trợ đồng thời module ESM, CJS giúp tối ưu kích thước bundle của dự án.

🚀 Hướng dẫn cài đặt (Quick Start)

1. Cài đặt qua NPM (Khuyên dùng)

npm install @quorix/ui

2. Tích hợp vào dự án

Nhúng các module cốt lõi vào file entry chính của dự án:

// Nhúng CSS tổng
import '@quorix/ui/dist/quorix.min.css';

// Nhúng Javascript lõi để xử lý tương tác
import '@quorix/ui/dist/quorix.min.js';

Sử dụng CSS Module riêng lẻ

Nếu bạn muốn tối ưu kích thước hơn nữa, Quorix UI hỗ trợ import theo từng phần:

import '@quorix/ui/css/colors';
import '@quorix/ui/css/components';
import '@quorix/ui/css/article-extensions';
import '@quorix/ui/css/ai-search';
import '@quorix/ui/css/animations';

Sử dụng qua CDN

Để tạo prototype nhanh gọn nhất, bạn có thể nhúng trực tiếp qua mạng lưới unpkg:

<link rel="stylesheet" href="https://unpkg.com/@quorix/ui@latest/dist/quorix.min.css">
<script src="https://unpkg.com/@quorix/ui@latest/dist/quorix.min.js" defer></script>

Kiểm tra trước khi release

Chạy đầy đủ cổng kiểm tra trước khi publish:

npm run verify
npm pack --dry-run

Bộ lệnh publish npm/CDN và push GitHub nằm trong RELEASE.md.

🏗️ Cấu trúc kiến trúc phân tầng

Kiến trúc CSS tại css/ được tổ chức thành 15 module rõ vai trò, giúp hệ thống dễ bảo trì, dễ đóng gói và dễ mở rộng khi sản phẩm phát triển:

♿ Tiêu chuẩn tiếp cận (WCAG 2.1 AA)

Tính phổ quát và dễ sử dụng luôn là ưu tiên hàng đầu. Quorix UI được thiết kế và kiểm soát theo các kỳ vọng chính của chuẩn tiếp cận WCAG 2.1 AA:

Opt-in Motion Engine: Animation chỉ được phép kích hoạt nếu an toàn. Nếu trình duyệt của người dùng cấu hình giảm thiểu chuyển động, chúng tôi sẽ tuân theo:
```
@media (prefers-reduced-motion: no-preference) { /* Animation an toàn */ }
```
Color Contrast: Mọi text phụ trợ (secondary text) cũng như đường ranh giới linh kiện luôn được duy trì tỷ lệ tương phản tối thiểu là 4.5:1 so với nền.
Screen Readers thông minh (Hệ sinh thái Toast):
- Các thông báo thông thường được bọc aria-live="polite".
- Các thông báo báo lỗi quan trọng được đẩy lên assertive kèm thuộc tính role="alert" để chiếm luồng của trình đọc màn hình ngay lập tức.
ARIA Tabs: Tab group dùng tablist / tab / tabpanel, đồng bộ aria-selected và hidden, đồng thời hỗ trợ điều hướng bằng Arrow/Home/End.
Typography FOUT: Giảm thiểu triệt để sự cố giật thay đổi font (FOUT - Flash of Unstyled Text) bằng chuỗi dự phòng (AWS Diatype -> Nunito -> ui-rounded) đi đôi với font-display: swap.

🔍 Sự minh bạch (Known Limitations & Testing)

Để duy trì tính minh bạch cho một dự án mã nguồn mở, chúng tôi khuyến cáo rõ các giới hạn sau:

Bẫy con trỏ (Focus Trapping): Việc bẫy sự kiện phím Tab để focus không bị nhảy ra ngoài thẻ Modals đòi hỏi người dùng phải bật JavaScript. Không thể bẫy focus an toàn nếu chỉ dùng mỗi CSS.
Môi trường đã test Screen Reader:
- Windows: Công cụ NVDA kết hợp Google Chrome.
- macOS: Công cụ VoiceOver kết hợp Apple Safari.
Kêu gọi cộng đồng: Team phát triển đang liên tục giám sát runtime tab-order. Nếu bạn phát hiện lỗi hệ thống focus bị sai luồng hoặc DOM bị nhảy lệch, vui lòng mở Issue trên nền tảng GitHub.

🛠️ Ví dụ sử dụng (Code Example)

Cấu trúc giao diện cơ bản của một thẻ Card mang phong cách Glassmorphism:

<div class="qx-card qx-glass p-6 max-w-sm">
  <div class="qx-card-header pb-4 border-b">
    <h3 class="font-semibold text-lg text-primary">Cập nhật hệ thống</h3>
  </div>
  <div class="qx-card-body pt-4">
    <p class="text-secondary mb-4">Phiên bản 2.1.8 đã sẵn sàng để tải xuống.</p>
    <button class="qx-btn qx-btn-primary flex items-center gap-2">
      <i class="lucide-download" aria-hidden="true"></i>
      Tải ngay
    </button>
  </div>
</div>

Primitive cho bài viết và media

Quorix UI đã bổ sung các primitive được rút ra từ giao diện bài viết của Quorix Việt Nam:

.qx-article-body-layout cho cụm Mục lục + nội dung đọc được căn giữa.
.qx-article-content / .qx-readable-content với biến --qx-readable-content-max.
.qx-toc-panel, .qx-toc-link, .qx-article-toc cho mục lục sticky.
Styling tương thích Hugo/Markdown cho .qx-prose .highlight* và bảng trong nội dung.
.article-media, .article-mermaid, .qx-video-player, và .qx-youtube-player cho media trong bài viết.
.qx-article-hero, .qx-hero-meta, .qx-meta-list, .qx-project-info-grid, và .qx-service-info-grid cho project/service detail.
.qx-ai-search, .qx-search-*, .qx-fast-*, .qx-source-*, .qx-chat-*, và .qx-confidence-* cho giao diện search/chat.
.qx-audio-player / .qx-speech-player với điều khiển icon-only và --qx-audio-progress.

Ví dụ audio declarative:

<div class="qx-audio-player" data-qx-audio-player aria-label="Article audio">
  <audio preload="metadata" src="/speech.mp3"></audio>
  <div class="qx-audio-player__shell">
    <button class="qx-audio-player__play" data-qx-audio-toggle aria-label="Play audio"></button>
    <div class="qx-audio-player__body">
      <input type="range" min="0" max="100" value="0" data-qx-audio-progress aria-label="Audio progress">
    </div>
  </div>
</div>

JavaScript core cũng hiểu các attribute cũ dạng data-audio-*, nên quorix-vietnam có thể migration dần.