@thangnqdev/ui

AETHER — Spatial Optics & Enterprise-Grade Component Infrastructure for React & Tailwind CSS.

An enterprise-ready architectural UI system engineered for complex SaaS, Fintech, AI Agents, ERP dashboards, and spatial web applications. Features machine-readable contracts (llms.txt, ui-contract.json), 100% SSOT parity, WCAG 2.1 AA accessibility tiers, hydration-safe SSR, and modular standalone CSS packaging.

📦 Cài Đặt (Installation)

npm install @thangnqdev/ui
# or
pnpm add @thangnqdev/ui
# or
yarn add @thangnqdev/ui

Peer Dependencies

Yêu cầu react và react-dom (>= 18.0.0 hoặc 19.0.0):

npm install react react-dom

🎨 Thiết Lập Nhanh (Quickstart)

Cách 1: Sử dụng Standalone All-In-One CSS

File styles.css đã được biên dịch trọn gói toàn bộ hệ thống Apple Liquid Glass, màu sắc HSL, font SF Pro và các class tiện ích:

// Trong file src/main.tsx hoặc app/layout.tsx
import '@thangnqdev/ui/styles.css';

import { ThemeProvider, Button, DataTablePro, DatePicker, Combobox } from '@thangnqdev/ui';

export default function App() {
  return (
    <ThemeProvider defaultTheme="light">
      <Button variant="primary">Primary Action</Button>
    </ThemeProvider>
  );
}

ThemeProvider mặc định sử dụng theme light, vì vậy có thể bỏ prop defaultTheme nếu ứng dụng không cần chọn theme khác. Các giá trị dark và system vẫn được hỗ trợ.

Cách 2: Sử dụng Domain Modular Subpath CSS (Tối ưu hóa Bundle Size)

Mỗi domain module có stylesheet độc lập đã được biên dịch toàn bộ utility class và design tokens:

import { Button, IconButton } from '@thangnqdev/ui/buttons';
import '@thangnqdev/ui/buttons/styles.css';

import { Modal, ModalTitle, ModalBody } from '@thangnqdev/ui/overlays';
import '@thangnqdev/ui/overlays/styles.css';

🏛️ Kiến Trúc Hệ Thống (Architectural Pillars)

1. Single Source of Truth (SSOT) Invariant Guarantee

Toàn bộ metadata component, public exports, ui-contract.json và llms.txt được liên kết trực tiếp với COMPONENT_REGISTRY (145 components). CI tự động kiểm tra tính bất biến 1-to-1: $$\text{Registry Exports} \equiv \text{Public TS Exports} \equiv \text{ui-contract.json} \equiv \text{llms.txt}$$

2. Ba Cấp Độ Accessibility Rõ Ràng (A11y Tiers)

Không overclaim accessibility; mọi primitive được phân loại minh bạch:

• native: Các thẻ nền tảng browser (Container, Grid, Heading, Text, Link, Portal, Divider...).
• supported: Các component composite hỗ trợ ARIA attributes và keyboard shortcuts.
• verified: Các interactive primitives đã vượt qua kiểm thử WAI-ARIA pattern đầy đủ và automated audit bằng axe-core (Button, Modal, FocusTrap, DatePicker, DateRangePicker, TimePicker, Tooltip, SplitButton, Checkbox, RangeSlider, Tabs, Accordion, DataTablePro...).

3. Chuẩn Hóa State với useControllableState

Mọi stateful component (CurrencyInput, NumberInput, Popover, DatePicker, Combobox, Checkbox...) hỗ trợ cả Controlled và Uncontrolled mode với cam kết:

• Khi controlled, UI luôn trung thực với value prop (không bao giờ lệch khi parent reject update).
• Chuyển đổi trạng thái mượt mà, hỗ trợ open / defaultOpen / onOpenChange và value / defaultValue / onChange.

4. Hydration-Safe SSR cho Next.js / Remix

ThemeProvider và toàn bộ overlay components khởi tạo an toàn, đồng bộ theme client-side sau mount để loại bỏ hoàn toàn lỗi React hydration mismatch.

🛠️ Hướng Dẫn Tùy Biến (Customization Guide)

1. Tùy Biến Toàn Cục bằng CSS Variables (Global Theming)

:root {
  /* 🔤 Font chữ & Monospace */
  --ui-font-sans: 'Plus Jakarta Sans', 'Inter', sans-serif;
  --ui-font-mono: 'JetBrains Mono', 'Fira Code', monospace;

  /* 🎨 Màu chủ đạo thương hiệu (Brand Colors) */
  --ui-primary: #6366f1;
  --ui-primary-hover: #4f46e5;
  --ui-primary-glow: rgba(99, 102, 241, 0.35);
  --ui-accent: #ec4899;

  /* 📐 Bo góc */
  --ui-radius-lg: 16px;
}

.dark, [data-theme="dark"] {
  --ui-primary: #818cf8;
  --ui-bg-page: #09090b;
  --ui-bg-secondary: #18181b;
}

🤖 Machine-Readable Contracts for AI Agents

Thư viện cung cấp hợp đồng chuẩn máy cho các trợ lý AI (Antigravity, Claude Code, Cursor, Codex):

• llms.txt: Đặc tả toàn diện cấu trúc import, signature, và quy tắc lập trình.
• ui-contract.json: Schema JSON chặt chẽ phục vụ validate và sinh code tự động.

🧪 Quality Gates & Kiểm Thử

# Kiểm tra strict TypeScript
npm run typecheck

# Chạy toàn bộ 115+ test cases (A11y, Axe, Invariant, SSR, Controllable State)
npm test

# Kiểm tra tính bất biến SSOT
npm run test:ssot

# Kiểm tra WAI-ARIA & Axe automated scans
npm run test:a11y

# Kiểm tra Server-Side Rendering
npm run test:ssr

# Quy trình Prepack Gate trước khi phát hành
npm run prepack

📄 License

MIT © 2026 AETHER Spatial UI