Shared Design System

Bộ thư viện thành phần giao diện dùng chung (Common Components) và hệ thống Design Tokens dành cho kiến trúc Microfrontend Portal.

Current Version: v1.7.0 — Hệ thống đã được nâng cấp toàn diện với TypeScript, Tailwind Preset và 23+ components sẵn sàng cho sản xuất.

🚀 Cài đặt

Thư viện này được quản lý như một package nội bộ trong monorepo. Bạn có thể sử dụng trực tiếp trong các ứng dụng MFE:

# Trong package.json của MFE
"dependencies": {
  "shared-design-system": "workspace:*"
}

Dùng trong code:

import { Button, Card, tokens } from 'shared-design-system';

🎨 Tích hợp Tailwind CSS

Thư viện cung cấp một Tailwind Preset để đồng bộ hóa bảng màu và cấu hình font.

1. Cấu hình tailwind.config.ts

Trong project MFE của bạn, hãy import và sử dụng preset:

import type { Config } from 'tailwindcss';
import sharedPreset from 'shared-design-system/tailwind.preset';

const config: Config = {
  presets: [sharedPreset],
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    // Quan trọng: Thêm đường dẫn tới file source của shared-design-system để Tailwind scan classes
    "./node_modules/shared-design-system/src/components/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      // Các tùy chỉnh riêng cho MFE của bạn
    },
  },
  plugins: [],
};

export default config;

🧱 Hệ thống Thành phần (Components)

🔹 Cơ bản (Basic Elements)

• Button: Nút bấm đa năng (primary, secondary, danger, ghost).
• Badge: Nhãn trạng thái (success, warning, danger, info).
• Typography: Hệ thống phân cấp chữ (Heading, Text, SectionHeader).
• LoadingSpinner: Hiệu ứng xoay khi đang tải dữ liệu.
• Divider: Đường kẻ phân tách nội dung.
• Progress: Thanh tiến trình (Linear Progress).

🔹 Nhập liệu (Form & Inputs)

• Input / Textarea: Ô nhập văn bản hỗ trợ label và validation state.
• Select: Menu lựa chọn dropdown.
• Checkbox / Radio: Lựa chọn đơn hoặc nhiều.
• Switch: Nút gạt bật/tắt hiện đại.

🔹 Điều hướng & Cấu trúc (Navigation & Layout)

• Breadcrumbs: Chỉ dẫn vị trí trang.
• Tabs: Hệ thống chuyển đổi nội dung, hỗ trợ truyền items cho tiện lợi.

  <Tabs 
    value={currentTab} 
    onChange={setCurrentTab} 
    items={[
      { label: 'Tổng quan', value: 'overview' },
      { label: 'Cài đặt', value: 'settings' }
    ]}
  />

• Steps: Quy trình thực hiện (Workflow).
• Stack: Quản lý khoảng cách tự động giữa các phần tử.
• Card: Container bọc nội dung cao cấp.

🔹 Dữ liệu & Danh sách (Data Display)

• Table: Component xây dựng bảng dữ liệu chuyên nghiệp theo hướng data-driven.

  import { Table } from 'shared-design-system';
  
  <Table 
    columns={[
      { key: 'name', label: 'Họ tên' },
      { key: 'role', label: 'Vai trò' }
    ]}
    data={[
      { name: 'Nguyễn Văn A', role: 'Admin' },
      { name: 'Lê Thị B', role: 'User' }
    ]}
  />

• List & ListItem: Danh sách hiển thị theo cấu trúc mảng hoặc children.

  import { List, ListItem, Button } from 'shared-design-system';
  
  <List 
    items={[
      { title: 'Thông tin người dùng', id: 1 },
      { title: 'Cài đặt hệ thống', id: 2 }
    ]}
    renderItem={(item) => (
      <ListItem action={<Button size="sm">Sửa</Button>}>
        {item.title}
      </ListItem>
    )}
  />

• Tag/Chip: Nhãn dán hỗ trợ nút đóng (close).
• Avatar: Ảnh đại diện hoặc tên viết tắt.
• ReadOnlyField: Hiển thị dữ liệu ở chế độ chỉ đọc.
• Skeleton: Placeholder khi đang tải.

🔹 Tương tác (Feedback & Overlays)

• Alert: Thông báo mức độ nghiêm trọng (success, error, etc.).
• Tooltip: Chú thích khi di chuột.
• ConfirmModal:

  <ConfirmModal
    isOpen={showModal}
    title="Xác nhận xóa"
    message="Bạn có chắc chắn muốn xóa bản ghi này?"
    variant="danger"
    onConfirm={handleDelete}
    onCancel={() => setShowModal(false)}
  />

🔧 Design Tokens

Tránh sử dụng mã màu hardcoded. Hãy sử dụng hệ thống tokens để đảm bảo tính nhất quán và hỗ trợ Theming trong tương lai.

import { tokens } from 'shared-design-system';

const style = {
  backgroundColor: tokens.color.surfaceAlt,
  padding: tokens.spacing[4],
  borderRadius: tokens.radius.lg,
  boxShadow: tokens.shadow.md
};

🛠 Nguyên tắc phát triển

1. Strict Typing: Tất cả components phải có Props interface được export rõ ràng.
2. Stateless First: Ưu tiên logic xử lý ở phía ứng dụng, component chỉ tập trung vào hiển thị (UI).
3. Semantic HTML: Sử dụng đúng các thẻ HTML (button, nav, section) để tối ưu SEO và Accessibility.
4. Composition Over Inheritance: Tận dụng children prop để tạo ra các layout linh hoạt.

📦 Quy trình Build

# Kiểm tra lỗi Type
npm run typecheck

# Build ra thư mục dist/
npm run build

Lưu ý: Thư mục dist/ sẽ chứa mã JS đã transpose và các file .d.ts. Luôn chạy build trước khi tích hợp vào Portal.

© 2024 Portal Design System Team.