UICONV — Quy ước giao diện —
|
|
| Version |
1.0 |
| Date |
YYYY-MM-DD |
| Author |
(skill ba-3-specification, activity uiconv) |
| Status |
🟡 Draft |
| Approved by |
Designer: — · PO: — |
| Source |
<prototype / design system / SAD §7 / GLOBAL_UI_CONVENTION của dự án / DEC-nn> |
| Scope |
Toàn project — mọi SRS và WF có PRODUCT = screen |
| Profile |
screen · … · … |
Change Log
| Version |
Date |
Người sửa |
Thay đổi |
CR |
| 1.0 |
|
|
Bản đầu |
— |
Vai trò của tài liệu này. Một project có nhiều SRS, mỗi lần chạy tối đa 3 US. Không có
tài liệu này thì mỗi SRS tự đặt một kiểu phân trang, một vị trí toast, một định dạng ngày.
SRS và WF tham chiếu mục ở đây thay vì định nghĩa lại; muốn lệch phải ghi vào §12.
Thứ tự ưu tiên khi lệch: Design system của dự án (nếu có) > Prototype đã duyệt > UICONV
SRS từng US. SRS chỉ được ghi khác UICONV khi có dòng ở §12.
0. Nguồn
|
|
| Design system |
(tên + version + link, hoặc "Chưa có — dev chọn theo NFR, quy ước ở đây là ràng buộc tối thiểu") |
| Prototype tham chiếu |
(đường dẫn / URL / mục SAD, phiên bản, ngày) |
| Guideline sẵn có của dự án |
(vd: GLOBAL_UI_CONVENTION.md — nếu có thì file này chỉ bổ khuyết, không chép lại) |
| Ai sở hữu quy ước |
BA đề xuất · Designer duyệt · PO duyệt phần text/giọng văn |
| Nền tảng |
Web desktop / web responsive / app di động — (theo BRIEF) |
1. Khung layout
|
|
| Grid |
(số cột · gutter px · max-width px) |
| Header cố định |
Có / Không — chứa: (logo, tìm kiếm toàn cục, ngôn ngữ, tài khoản…) |
| Sidebar / menu |
Trái cố định / thu gọn được / không có |
| Footer |
Có / Không — chứa: |
| Breakpoint |
Khoảng (px) |
Sidebar |
Bảng dữ liệu |
Form |
| Desktop |
≥ 1024 |
Hiện |
Bảng |
2 cột |
| Tablet |
768–1023 |
Thu gọn icon |
Bảng cuộn ngang |
1 cột |
| Mobile |
< 768 |
Ẩn sau nút menu |
Card |
1 cột |
2. Điều hướng
| Câu hỏi |
Quy ước |
| Quay lại từ màn hình chi tiết/form |
Nút Back và breadcrumb — cả hai |
| Quay lại có giữ trạng thái danh sách (trang, bộ lọc, sắp xếp)? |
✅ Giữ, qua query string |
| Vào bằng URL trực tiếp với id không tồn tại |
Trang trạng thái "Không tìm thấy" + nút về danh sách |
| Vào bằng URL trực tiếp không có quyền |
Trang "Không có quyền" + nút về trang chủ; không lộ tên bản ghi |
| Rời màn hình khi form đang dở |
Modal xác nhận "Rời trang? Thay đổi chưa lưu sẽ mất." |
| Menu với chức năng không có quyền |
❌ Ẩn (W7) |
| Mở chi tiết |
Cùng tab, đổi URL |
3. Danh sách
|
|
| Kiểu phân trang |
Offset (page, size) / Cursor / Cuộn vô hạn |
| Số dòng mỗi trang |
Mặc định … · tuỳ chọn … |
| Sắp xếp mặc định |
(vd: ngày tạo giảm dần) |
| Bấm vào dòng |
Mở chi tiết / Chỉ nút "Chi tiết" mới mở |
| Cột hành động |
Cột cuối, icon + tooltip / Menu ⋯ |
| Chọn nhiều dòng |
Checkbox cột đầu, thanh hành động hàng loạt xuất hiện phía trên |
| Tìm kiếm |
Gõ rồi Enter / Gợi ý sau khi ngừng gõ … ms |
| Bộ lọc |
Thanh ngang trên bảng (desktop) · nút "Lọc" mở bottom-sheet (mobile) |
| Cột trên mobile |
Bảng → card; card hiện tối đa … trường: (liệt kê thứ tự ưu tiên chung) |
4. Form
|
|
| Vị trí nút |
Lưu (nút chính) bên phải, Huỷ (nút phụ) bên trái nút Lưu |
| Đánh dấu bắt buộc |
Dấu * màu cảnh báo sau nhãn |
| Thời điểm validate |
Khi rời field (blur) và khi bấm Lưu |
| Vị trí message lỗi |
Ngay dưới field, thay chỗ hint; field viền cảnh báo |
| Lỗi nhiều field |
Focus vào field lỗi đầu tiên, cuộn tới nó |
| Lỗi từ server không gắn field |
Banner đầu form |
| Sau lỗi mạng/5xx |
🔴 Giữ nguyên dữ liệu đã nhập, mở lại nút Lưu |
| Đang gửi |
Khoá toàn form, spinner trong nút Lưu, nhãn đổi "Đang lưu…" |
| Huỷ khi có thay đổi |
Modal xác nhận |
| Nhãn field |
Trên field (không đặt cạnh trái) |
| Nút Lưu khi form chưa hợp lệ |
Bấm được, hiện lỗi / 🔒 disable — (chọn một) |
5. Phản hồi hệ thống
| Loại |
Dùng khi |
Vị trí |
Thời lượng |
Có nút đóng |
| Toast thành công |
Lưu/xoá thành công |
Góc trên phải (desktop) · trên cùng (mobile) |
3 s tự đóng |
✅ |
| Toast lỗi |
Lỗi không gắn field, có thể thử lại |
Như trên |
Không tự đóng |
✅ |
| Modal xác nhận |
Hành động không hoàn tác được (xoá, gửi duyệt) |
Giữa màn |
— |
Nút chính bên phải; hành động nguy hiểm dùng nút nguy hiểm |
| Inline dưới field |
Lỗi validation |
Dưới field |
Tới khi sửa |
— |
| Banner trong vùng |
Lỗi tải một vùng dữ liệu |
Trong vùng đó |
Tới khi thử lại |
Nút Thử lại |
| Trang trạng thái |
404 / 403 / lỗi toàn trang |
Toàn trang |
— |
Nút về danh sách/trang chủ |
6. Trạng thái chuẩn
| Trạng thái |
Hiển thị |
Text mặc định (VI) |
Text (EN) |
Nút |
| Đang tải danh sách |
Skeleton … dòng |
— |
— |
— |
| Đang tải chi tiết/form |
Skeleton theo bố cục |
— |
— |
— |
| Đang tải cục bộ (dropdown, tính lại) |
Spinner nhỏ tại chỗ |
— |
— |
— |
| Rỗng — chưa có dữ liệu nào |
Minh hoạ + câu dẫn + nút chính |
"Chưa có <đối tượng> nào." |
|
Tạo mới |
| Rỗng — bộ lọc không khớp |
Câu dẫn + nút phụ (không minh hoạ, để khác loại trên) |
"Không tìm thấy kết quả phù hợp với bộ lọc." |
|
Xoá lọc |
| Lỗi tải |
Banner trong vùng |
"Không tải được dữ liệu." |
|
Thử lại |
| Không có quyền |
Trang trạng thái |
"Bạn không có quyền truy cập nội dung này." |
|
Về trang chủ |
| Không tìm thấy |
Trang trạng thái |
"Không tìm thấy nội dung yêu cầu." |
|
Về danh sách |
SRS §2.3.6 chỉ ghi phần khác với bảng này (vd: câu dẫn riêng cho đối tượng), còn lại tham chiếu.
7. Ẩn · khoá · read-only (quy tắc W7)
| Trạng thái |
Trình bày |
Bắt buộc kèm |
❌ ẩn |
Không render |
— |
🔒 disable |
Mờ 45%, con trỏ mặc định |
Tooltip nêu lý do khi hover/focus |
👁 read-only |
Giá trị dạng text, không viền ô nhập, nhãn giữ nguyên |
— |
8. Định dạng hiển thị
SRS §4.3 tham chiếu bảng này; chỉ ghi khác khi có dòng ở §12.
| Loại |
Định dạng |
Ví dụ |
Ghi chú |
| Ngày |
dd/MM/yyyy |
30/08/2026 |
|
| Ngày giờ |
dd/MM/yyyy HH:mm |
30/08/2026 14:05 |
Múi giờ hiển thị: … (theo người dùng / cố định UTC+7) |
| Lưu trữ thời gian |
ISO-8601 UTC |
|
Khớp API §1 |
| Số |
#,##0 |
1.234.567 |
Dấu phân cách: … |
| Tiền |
#,##0 ₫ |
1.234.567 ₫ |
Làm tròn: … · đa tiền tệ: … |
| Phần trăm |
0,0 % |
12,5 % |
|
| Rỗng / null |
— |
|
Thống nhất toàn hệ thống |
| Số lớn (id) |
Hiển thị nguyên văn chuỗi |
|
Không format |
9. Ngôn ngữ và giọng văn
|
|
| Ngôn ngữ hỗ trợ |
VI (mặc định) · EN · … — thiếu bản dịch ⇒ hiện khoá hay VI? (chọn một) |
| Xưng hô |
"bạn" / không xưng hô |
| Thông điệp lỗi |
Nói vì sao và làm gì tiếp; không mã kỹ thuật; kết thúc bằng dấu chấm |
| Nhãn nút |
Động từ, viết hoa chữ đầu: "Tạo mới", "Lưu", "Huỷ" |
| Tiêu đề màn hình |
Danh từ: "Danh sách cửa hàng" |
| Độ dài nhãn tối đa |
… ký tự — để không vỡ ở ngôn ngữ dài (KO/DE) |
| Khoá i18n |
<scr>.<thành phần>.<thuộc tính> — vd scr01.search.ph |
10. Dãy mã lỗi
| Dãy |
Module / phạm vi |
Số kế tiếp chưa dùng |
Ai cấp |
E-<DOMAIN>- |
|
0001 |
BA |
11. Từ vựng thành phần
WF §3.x.2 cột "Kiểu trình bày" chỉ dùng từ ở cột đầu. Cột thứ hai map sang design system khi có.
| Kiểu trình bày |
Component trong design system |
Dùng khi |
| Nút chính |
|
Một hành động chính mỗi màn hình |
| Nút phụ |
|
Huỷ, hành động thứ cấp |
| Nút nguy hiểm |
|
Xoá, huỷ đơn — luôn kèm modal xác nhận |
| Liên kết |
|
Điều hướng trong text |
| Ô nhập |
|
|
| Ô nhập số |
|
|
| Chọn 1 |
|
≤ 7 lựa chọn: radio · > 7: dropdown có tìm |
| Chọn nhiều |
|
|
| Chọn ngày / khoảng ngày |
|
|
| Công tắc |
|
Bật/tắt có hiệu lực ngay |
| Bảng |
|
Desktop |
| Card |
|
Mobile, hoặc dữ liệu ít cột |
| Badge trạng thái |
|
Trạng thái vòng đời (BR §3) |
| Tab |
|
Nhóm nội dung cùng cấp trong một màn hình |
| Modal |
|
Form ngắn ≤ 6 field, xác nhận |
| Drawer |
|
Form dài, chi tiết nhanh |
| Bottom-sheet |
|
Bộ lọc trên mobile |
| Toast |
|
§5 |
| Skeleton |
|
§6 |
12. Ngoại lệ đã duyệt
SRS/WF lệch quy ước ⇒ phải có dòng ở đây. Không có dòng ⇒ lệch là lỗi, không phải quyết định.
| # |
Tài liệu |
Mục lệch |
Quy ước |
Thực tế |
Vì sao |
Ai duyệt |
Ngày |
13. Open Questions
| ID |
Câu hỏi |
Hỏi ai |
Từ ngày |
Chặn gì |
Tự chấm
| # |
Tiêu chí |
☐/✅ |
| 1 |
Mọi ô "chọn một" đã chọn, không còn dấu / giữa các phương án |
|
| 2 |
§6 có hai trạng thái rỗng trông khác nhau |
|
| 3 |
§8 có múi giờ hiển thị và quy tắc làm tròn tiền |
|
| 4 |
§11 mọi kiểu trình bày dùng trong WF hiện có đều có dòng |
|
| 5 |
Có chữ ký Designer (hoặc ghi rõ dự án không có Designer ⇒ PO ký thay, DEC-nn) |
|
