Chuyển tới nội dung chính

Tiêu chuẩn Layout Trang (Page Layout)

Tài liệu này quy định cấu trúc chuẩn của một trang (Page) trong hệ thống VPPOS Admin để đảm bảo tính nhất quán về mặt thị giác và luồng trải nghiệm.

1. Cấu trúc chuẩn của một Page​

Mọi trang chức năng thông thường nên được bọc trong bộ ba component từ @vppos/core/ui/react: PageContainer, PageHeader, và PageContent.

import { PageContainer, PageHeader, PageContent } from "@vppos/core/ui/react";

const MyPage = () => {
  return (
    <PageContainer>
      <PageHeader
        title="Tên Trang"
        breadcrumbs={[...]}
        actions={<Button>Thêm mới</Button>}
      />

      <PageContent>
        {/* Nội dung chính của trang */}
      </PageContent>
    </PageContainer>
  );
};

2. PageContainer​

Là component bao ngoài cùng, chịu trách nhiệm quản lý khoảng cách (padding), độ rộng tối đa (max-width) và hiệu ứng chuyển cảnh khi chuyển trang.

  • Props:
    • fluid: (Boolean) Nếu true, trang sẽ chiếm 100% chiều rộng và bỏ padding mặc định (thường dùng cho các Dashboard phức tạp hoặc màn hình Sale).
    • className: Cho phép bổ sung class CSS tùy biến.

3. PageHeader​

Chứa các thông tin định danh trang và các nút hành động chính.

  • Title: Luôn sử dụng tiêu đề ngắn gọn, viết hoa (đã được style tự động).
  • Subtitle: (Tùy chọn) Mô tả ngắn gọn chức năng của trang.
  • Breadcrumbs: (Bắt buộc) Đường dẫn điều hướng.
    • Cấp 1: Luôn là "Trang chủ" (Home) trỏ về /dashboard/overview.
    • Cấp 2: Tên Module (ví dụ: Vai trò & Phân quyền).
    • Cấp 3: Tên trang hiện tại (In đậm, không link).
  • Actions: Khu vực bên phải dành cho các nút hành động (Thêm mới, Export, Filter...).

4. PageContent​

Khu vực chứa nội dung chính của trang. Component này đã tích hợp sẵn hiệu ứng animate-in fade-in để tạo cảm giác mượt mà khi dữ liệu được load.

  • Layout phổ biến trong PageContent:
    • StatCardGrid: Hiển thị các con số thống kê ở đầu trang.
    • TableToolbar: Chứa thanh tìm kiếm và các icon chức năng của bảng.
    • Table: Hiển thị danh sách dữ liệu chính.

5. Hệ thống Khoảng cách (Spacing & Layout)​

Hệ thống khoảng cách là yếu tố quan trọng nhất để tạo nên sự chuyên nghiệp và đồng bộ. Luôn sử dụng các đơn vị chuẩn của Tailwind.

Quy tắc Gap (Khoảng cách giữa các phần tử)​

  • gap-1 (4px) / gap-2 (8px): Dùng cho các nhóm cực nhỏ như (Icon + Text) trong Badge hoặc Button.
  • gap-3 (12px) / gap-4 (16px): Khoảng cách tiêu chuẩn giữa các phần tử trong Toolbar, các Input trong Form, hoặc giữa các nút hành động.
  • gap-6 (24px): Khoảng cách giữa các khối nội dung lớn (ví dụ: giữa các Card thống kê, hoặc giữa Header và Content) trên Desktop.

Quy tắc Padding (Khoảng cách lề trong)​

  • Button: px-4 py-2 hoặc px-3 py-1.5 (tùy size).
  • Input: px-4 py-2.5.
  • Card / Modal / Sheet: p-4 (mobile) và p-6 (desktop).
  • Page Container: px-2 py-2 (mobile) và px-4 py-4 (desktop) - được quản lý bởi PageContainer.

Quy tắc Margin (Khoảng cách lề ngoài)​

  • mx-auto: Luôn dùng cho các container trung tâm.
  • mb-4: Khoảng cách dưới của các tiêu đề nhóm hoặc các đoạn văn bản.
  • mb-6: Khoảng cách dưới của PageHeader hoặc giữa các section chính trên trang.

6. Typography & Màu sắc (Typography & Colors)​

Hệ thống Typography ưu tiên sự thanh thoát, tránh cảm giác "dày" và nặng nề.

4. Typography Baseline​

  • Standard Text: font-medium (500) is the baseline for all labels, buttons, and table content.
  • Avoid Bold: Do not use font-bold or font-semibold unless specifically highlighting critical numbers or status labels.
  • Scale: Use text-sm for data, text-base for primary labels, and text-xl/2xl for page titles.

5. Layout Best Practices​

  • Page Structure: Use PageContainer -> PageHeader -> PageContent.
  • Modal Grouping: Always wrap all Modals, Drawers, and Overlays in a single Fragment <> ... </> at the end of the PageContainer. This prevents the flex-col gap-* from applying extra spacing to hidden components.
  • Table Height: For data-heavy pages (Admin lists), use autoHeight={true} on the Table component to allow the entire page to scroll naturally. Avoid fixed maxHeight unless inside a small Dashboard card.
  • Shadows: Use shadow-sm for primary containers and shadow-md for interactive hover states. Avoid shadow-lg/xl except for top-level floating modals.
  • Secondary/Muted: text-slate-500 (Subtitle, helper text).

7. Bo góc & Đổ bóng (Border Radius & Shadows) - Chuẩn Soft UI​

Sử dụng nguyên tắc phối hợp "Khung ngoài 2XL - Thành phần trong XL" để tạo sự cân đối và mềm mại.

Bo góc (Border Radius)​

  • Outer Containers (standalone): rounded-2xl (16px) — Dùng cho Card lớn độc lập, Modal container, Drawer panel.
  • Table Content Containers: rounded-xl (12px) — Dùng cho khung bao ngoài Table (Toolbar + Table + Pagination), vì đã có PageContainer/PageHeader bao ngoài, không cần góc quá tròn.
  • Interactive/Inner Elements: rounded-xl (12px) — Dùng cho Button, Input, Select, Tabs, Card con, và các thành phần tương tác bên trong.
  • Special: rounded-full cho Avatar, Toggle, và Badge trạng thái.

Đổ bóng (Shadows)​

  • Tương tác (Buttons/Cards): shadow-sm (Nhẹ nhàng, tinh tế).
  • Lớp nổi (Modal/Drawer/Dropdown): shadow-xl hoặc shadow-2xl (Để tách biệt không gian).
  • Lưu ý: Hạn chế dùng shadow-md vì nó thường tạo cảm giác quá "dày". Ưu tiên sử dụng border mỏng (gray-100/200) kết hợp với shadow nhẹ.

8. Các quy tắc chung (Best Practices)​

  1. Nhất quán: Luôn tuân thủ thứ tự: Breadcrumbs -> Title -> Actions.
  2. Icons: Ưu tiên Lu icons từ react-icons/lu. Tuy nhiên, có thể sử dụng các bộ icon khác (như Fi, Io, Pi) nếu bộ Lu không có icon phù hợp, đảm bảo kích thước và nét vẽ đồng bộ (size: 16-20).
  3. Trạng thái Trống/Tải: Luôn sử dụng EmptyState khi không có dữ liệu và Skeleton khi đang tải. Tránh để màn hình trắng hoặc dùng spinner đơn điệu.