@fui-org/fui-cli 0.1.1 → 0.3.0

package/skills/fui-skill/references/ui-layout-patterns.md

@@ -0,0 +1,176 @@
+# FUI Layout Patterns — page-container, master-detail, switch, dynamic label
+
+> File này sở hữu: **pattern layout trang: page-container sticky, master-detail 2 cột, v-switch, date init, dynamic label**.
+
+Các pattern layout và điều khiển bổ trợ. Rút ra từ project **security-manager**.
+
+> Xem thêm: [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [module-structure.md](module-structure.md).
+
+---
+
+## 1. Khởi tạo Date với moment()
+
+```json
+"data": [
+  {
+    "TuNgay":  "moment().format('YYYY-MM-DD')",
+    "DenNgay": "moment().format('YYYY-MM-DD')"
+  }
+]
+```
+
+> Giá trị là JS expression string — FUI sẽ eval nó khi khởi tạo. `moment()` có sẵn trong FUI runtime.
+
+---
+
+## 2. page-container + page-navigation Layout
+
+Dùng khi cần filter bar cố định phía trên, nội dung bên dưới scroll.
+
+```json
+{
+  "prop": "page-container grid-list-md fluid",
+  "rows": [
+    {
+      "prop": "page-navigation",
+      "cols": [
+        { "el": "f-date", "attr": { "v-model": "TuNgay", "label": "Từ ngày", "date-add": 0 }, "w": "2" },
+        { "el": "f-date", "attr": { "v-model": "DenNgay", "label": "Tới ngày", "date-add": 0 }, "w": "2" },
+        {
+          "el": "f-button",
+          "attr": { "color": "primary", "icon-text": "mdi-filter", "label": "Tìm", ":action": { "CALL": "getLogData" } },
+          "w": 3
+        }
+      ]
+    },
+    {
+      "prop": "",
+      "cols": [
+        { "el": "f-table", "attr": { "label": "Log viewer", ":items": "LogData" } }
+      ]
+    }
+  ]
+}
+```
+
+- `page-container` + `page-navigation` → filter bar sticky top
+- `f-table` không khai `:update-api` → readonly view; không truyền `:headers` → tự build header từ data
+
+---
+
+## 3. Dynamic Label từ State
+
+Dùng `:label` với expression để hiển thị thông tin context.
+
+```json
+{
+  "el": "f-title",
+  "attr": {
+    ":label": "sFullName + ` - ` + sDepartment"
+  }
+}
+```
+
+```json
+{
+  "el": "f-table",
+  "attr": {
+    ":label": "`${fTableTitle==''? 'Computer list' : fTableTitle}`"
+  }
+}
+```
+
+---
+
+## 4. v-switch — Toggle với Label
+
+```json
+{
+  "el": "v-layout",
+  "attr": {},
+  "innerHTML": [
+    {
+      "el": "v-switch",
+      "attr": {
+        "v-model": "switchResetPassword",
+        ":required": false,
+        "label": "Đặt lại mật khẩu"
+      },
+      "w": "12"
+    }
+  ]
+}
+```
+
+Dùng với `v-if` để hiện/ẩn field bổ sung:
+```json
+{
+  "el": "v-layout",
+  "attr": { "v-if": "switchResetPassword" },
+  "innerHTML": [...]
+}
+```
+
+---
+
+## 5. Master-Detail 2 Cột
+
+Pattern layout cha-con: bảng trái chọn row → watch → load bảng phải. Không cần mở window mới.
+
+> Nút mở detail đặt trong ô bảng: chọn `t-button` hay `t-menu` theo quy tắc ở
+> [ui-table-cell-patterns.md](ui-table-cell-patterns.md#khi-nào-dùng-t-button-vs-t-menu) — với
+> master-detail thì hành động là "xem/load dữ liệu liên quan" nên dùng `t-button`.
+
+**`data[]` và watch:**
+
+```json
+"data": [
+  { "dsParent": [], "dsDetail": [], "selectedId": null },
+  {
+    "getParent": { "API": "/SM_Parent_Select", "OUT": "dsParent" },
+    "getDetail": {
+      "API": "/SM_Detail_Select",
+      "IN": { "ParentID": "selectedId" },
+      "OUT": "dsDetail"
+    }
+  },
+  { "CALL": "getParent" }
+],
+"watch": {
+  "selectedId": { "CALL": "getDetail" }
+}
+```
+
+**Cột `t-button` trong bảng trái:**
+
+```json
+{
+  "text": "Chi tiết",
+  "value": "ParentID",
+  "align": "center",
+  "el": "t-button",
+  "attr": {
+    "icon-text": "mdi-eye",
+    "color": "primary",
+    ":outlined": true,
+    ":action": { "selectedId": "item.ParentID" }
+  }
+}
+```
+
+**Layout 2 cột:**
+
+```json
+{
+  "prop": "fluid grid-list-md",
+  "rows": [
+    {
+      "prop": "row wrap",
+      "cols": [
+        { "w": 5, "el": "f-table", "attr": { ":items": "dsParent", "item-key": "ParentID", ":headers": [...] } },
+        { "w": 7, "el": "f-table", "attr": { ":items": "dsDetail", "item-key": "DetailID", ":headers": [...] } }
+      ]
+    }
+  ]
+}
+```

package/skills/fui-skill/references/ui-patterns.md

@@ -0,0 +1,315 @@
+# FUI UI Patterns — Real-World Design Reference (Core)
+
+> File này sở hữu: **pattern UI cốt lõi: toolbar/filter, permission gate, checklist thiết kế giao diện**. Bảng/dialog/cross-window/layout đã tách sang các file `ui-*` riêng.
+
+Các pattern được rút ra từ project **security-manager** — dùng làm tham chiếu khi thiết kế module mới.
+
+File này chứa **core patterns** (data/watch/toolbar/action). Các nhóm pattern chuyên sâu đã tách ra — load thêm khi cần:
+
+| Cần làm | File |
+|---|---|
+| f-table + điều khiển trong ô (t-check/t-button/t-select/t-menu, ctrl-update, chip-group) | [ui-table-cell-patterns.md](ui-table-cell-patterns.md) |
+| Dialog/form popup (hidden-container, mở dialog với row, checkbox-list) | [ui-dialog-patterns.md](ui-dialog-patterns.md) |
+| Mở sub-window & trao đổi dữ liệu (`openWindow`, `#PARENT`/`#Win`) | [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md) |
+| Layout (page-container, master-detail, v-switch, date init, dynamic label) | [ui-layout-patterns.md](ui-layout-patterns.md) |
+
+---
+
+## 1. Cấu trúc `data[]` trong module.json
+
+`data` là mảng khởi tạo state + action. FUI xử lý tuần tự từ trên xuống dưới.
+
+**Quy ước tổ chức:**
+- Object **không có key action** (không có API, CALL, IF…) → khởi tạo state
+- Object **có key là tên hàm** → định nghĩa named action (tái sử dụng)
+- Object dạng `{ "API": ..., "OUT": ... }` hoặc `{ "CALL": ... }` ở cuối → tự chạy khi load xong
+
+```json
+"data": [
+  {
+    "dsUser": [],
+    "dsGroup": [],
+    "sDepartment": null,
+    "dlUserInfo": false
+  },
+  {
+    "getDepartment": { "API": "SM_DepartmentSelectAll", "OUT": "dsDepartment" },
+    "getGroup":      { "API": "SM_Group_SelectAll",    "OUT": "dsGroup" },
+    "getUser": {
+      "API": "SM_Users_SelectByDepGroup",
+      "IN": { "GroupID": "sGroup", "DepartmentID": "sDepartment" },
+      "OUT": "dsUser"
+    }
+  },
+  { "CALL": "getDepartment" },
+  { "CALL": "getGroup" }
+]
+```
+
+> **Auto-startup**: CALL ở cuối `data[]` sẽ tự chạy khi module load — không cần event handler riêng.
+
+---
+
+## 2. Cascading API Init
+
+Dùng `CALLBACK` để set giá trị từ kết quả API đầu tiên, rồi API tiếp theo tự chạy qua `watch`.
+
+```json
+"data": [
+  { "dsModule": [], "sModuleID": null },
+  {
+    "API": "/SM_Modules_SelectAll",
+    "OUT": "dsModule",
+    "CALLBACK": { "sModuleID": "dsModule[0].ModuleID" }
+  }
+],
+"watch": {
+  "sModuleID": { "CALL": "getFunctionRight" }
+}
+```
+
+> `sModuleID` được set từ CALLBACK → watch tự kích hoạt `getFunctionRight`. Không cần gọi thủ công.
+
+---
+
+## 3. Watch — Cascading Filter
+
+Khi filter thay đổi → tự reload data. Nhiều watch → mảng CALL.
+
+```json
+"watch": {
+  "sDepartment": { "CALL": "getUser" },
+  "sGroup":      { "CALL": "getUser" },
+  "sModuleID": [
+    { "CALL": "getUserModule" },
+    { "CALL": "getSysRight" },
+    { "CALL": "getFunctionRight" }
+  ]
+}
+```
+
+---
+
+## 4. Toolbar / Filter Row Pattern
+
+Row chứa filter fields và action buttons, `v-spacer` đẩy nhóm nút về phải.
+
+> **Chuẩn mực bố cục của hàng này: MỌI cột đều `"col": "shrink"`, trừ `v-spacer`.** Cột không `shrink` là cột được chia phần trống — kể cả cột `w` rỗng, kể cả nút. Thiếu `shrink` thì nút phình ra, hở khoảng giữa các nút, và nhóm cuối hàng không sát mép phải dù đã có `v-spacer`. Khuôn chuẩn + số đo trên framework thật: [controls-patterns.md](controls-patterns.md) §Hàng nhiều control (toolbar).
+
+```json
+{
+  "prop": "",
+  "cols": [
+    {
+      "el": "v-autocomplete",
+      "col": { "class": "shrink" },
+      "attr": {
+        "class": "flex-md-grow-0",
+        "style": "width:200px",
+        "v-model": "sGroup",
+        "label": "Group",
+        ":items": "dsGroup",
+        "item-text": "GroupName",
+        "item-value": "GroupID",
+        ":required": false
+      },
+      "w": "200"
+    },
+    {
+      "el": "v-text-field",
+      "col": { "class": "shrink" },
+      "attr": {
+        "class": "flex-md-grow-0",
+        "style": "width:200px",
+        "v-model": "UserID",
+        "label": "User ID",
+        "clearable": ""
+      },
+      "w": "200"
+    },
+    {
+      "el": "f-button",
+      "col": { "class": "shrink" },
+      "attr": {
+        ":checkvalid": false,
+        "color": "primary",
+        "label": "Tìm",
+        "icon-text": "mdi-magnify",
+        ":action": { "CALL": "getUser" }
+      }
+    },
+    { "el": "v-spacer", "attr": {} },
+    {
+      "el": "f-button",
+      "col": { "v-if": "vueData.user.SystemRight==9", "class": "shrink" },
+      "attr": {
+        ":checkvalid": false,
+        ":disabled": "!sGroup",
+        "color": "primary",
+        "label": "Add User",
+        "icon-text": "mdi-account-multiple-plus",
+        ":action": [
+          { "addNew": 1, "sUserID": "", "sUserName": "" },
+          { "dlUserInfo": true }
+        ]
+      }
+    }
+  ]
+}
+```
+
+**Quy tắc:**
+- Filter fields: `w` là px (`>= 25`) + `col: "shrink"`. Cặp `attr: { class: "flex-md-grow-0", style: "width:Xpx" }` ở ví dụ trên là **thừa** — `w` + `shrink` đã cho đúng bề rộng đó (đo được: `w:150` + `shrink` → đúng 150px ở cả V2 lẫn V3); giữ lại trong ví dụ vì đây là module production chép nguyên, viết mới thì bỏ đi
+- Nút tìm: ngay sau fields, cũng `col: "shrink"` (nút **không** shrink sẽ bị kéo dãn ra)
+- **Luôn là `class: "shrink"` / `"col": "shrink"`, không phải `shrink: true`** — dạng thuộc tính trần chỉ ăn ở V2, ở V3 nó trơ và cột giãn full
+- `v-spacer`: cột **duy nhất** không `shrink` — nó phải giãn được thì mới đẩy được nhóm sau sang phải
+- Nút Add/Delete admin: sau spacer, thêm `v-if` permission — `col: { "v-if": "…", "class": "shrink" }` (object khi cần thêm key, vẫn giữ `shrink`)
+- Không có `v-spacer` mà muốn canh phải cả hàng: `"prop": "row justify-end"`
+
+---
+
+## 5. Permission Gating
+
+Ẩn/hiện phần tử theo `SystemRight` của user.
+
+```json
+"col": { "v-if": "vueData.user.SystemRight>1" }
+"col": { "v-if": "vueData.user.SystemRight==9" }
+```
+
+- `>1` — visible với mọi user có quyền (không phải level thấp nhất)
+- `==9` — chỉ admin cao nhất mới thấy
+
+---
+
+## 6. IF/THEN/ELSE — Conditional Action
+
+Rẽ nhánh logic trong action hoặc CALLBACK.
+
+```json
+{
+  "IF": "TypeLoad==1",
+  "THEN": { "CALL": "getComputer" },
+  "ELSE": {
+    "IF": "TypeLoad==2",
+    "THEN": { "CALL": "getComputerDinied" },
+    "ELSE": { "CALL": "getComputerNotVisited" }
+  }
+}
+```
+
+- Condition: JavaScript expression dùng vueData fields trực tiếp (không cần `vueData.`)
+- Dùng nested IF/ELSE cho switch-case nhiều nhánh
+
+**Ứng dụng thực tế:** Module có nhiều chế độ xem (`TypeLoad`) — sau khi update, refresh đúng danh sách đang hiển thị.
+
+```json
+"data": [
+  { "TypeLoad": 1 }
+]
+```
+
+---
+
+## 7. CALLBACK Chaining
+
+CALLBACK là array → thực thi tuần tự.
+
+> **Nhiều lệnh thì BẮT BUỘC là mảng, mỗi lệnh một `{}` riêng.** Gộp `CALL` + `MESS` + `EXE` vào chung một object thì chỉ **một** lệnh chạy (ưu tiên `API` → `CALL` → `EXE` → `FUN` → `IF` → `MESS` → `MESSBOX`, mỗi nhánh `return` ngay), phần còn lại rơi im lặng — không error, không `[Vue warn]`. Luật đầy đủ + lý do trong runtime: [controls-patterns.md](controls-patterns.md) §QUY TẮC NỀN.
+
+```json
+"CALLBACK": [
+  { "MESS": "Cập nhật thành công." },
+  { "dlUserInfo": false },
+  { "CALL": "getUser" }
+]
+```
+
+```json
+"CALLBACK": [
+  { "CALL": "getUserModule" },
+  { "sUserDeptSelected": [], "dlAddUser": false },
+  { "MESS": "Thêm user thành công." }
+]
+```
+
+**Thứ tự thông dụng:** reload data → reset state → hiển thị message.
+
+---
+
+## 8. set — Cấu hình Module Level
+
+`set` ở root module.json — cấu hình behavior của toàn module.
+
+```json
+"set": {
+  "menu": false
+}
+```
+
+- `menu: false` — ẩn menu navigation (dùng cho sub-window, log viewer)
+
+> Module mở qua `openWindow`: khai báo `"set": { "menu": false }` trong module.json của module con —
+> **không** truyền `?menu=0` trong URL. Pattern đầy đủ (kể cả cách set động từ `data[]`):
+> [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+
+---
+
+## 9. CALLBACK với JavaScript Expression
+
+Dùng `{{ expression }}` trong CALLBACK để chạy code phức tạp sau API.
+
+```json
+"CALLBACK": "{{ _.forEach(dsUsers, (x)=> x.FunctionName = JSON.parse(x.FunctionName)) }}"
+```
+
+```json
+"CALLBACK": "{{ _.forEach(dsUserFunction, (x)=> x.FunctionName = JSON.parse(x.FunctionName)), _.forEach(dsUserFunction, (x)=> x.UserSysItem = JSON.parse(x.UserSysItem)) }}"
+```
+
+> Dùng khi API trả về JSON string cần parse thành object/array trước khi render.
+
+---
+
+## 10. script.js — Helper Functions
+
+`script.js` chứa helper functions gọi từ `v-on:click` hoặc action.
+
+```javascript
+// script.js
+function setFunction(user, fc) {
+    vueData.sFunctionSelected = [];
+    vueData.sUserSelected = [];
+    vueData.sUserSelected.push(user);
+    if (!fc) return;
+    vueData.dsFunctionRight.map((item) => {
+        if (fc.some(fci => fci.FunctionID == item.FunctionID)) {
+            vueData.sFunctionSelected.push(item.FunctionID.toString());
+        }
+    });
+}
+```
+
+Gọi từ `v-on:click` trong header:
+```json
+"v-on:click": "vueData.dlFunction = true; CALL(setFunction(item, item.FunctionName));"
+```
+
+> Functions trong `script.js` có thể access `vueData` trực tiếp. Dùng để xử lý logic phức tạp không thể làm bằng action JSON thuần.
+
+---
+
+## Checklist Thiết Kế UI
+
+> Checklist cấu trúc `module.json` (thứ tự `data[]`, grid wrapper, `w`, `v-on:`, `set`, JSON hợp lệ)
+> nằm ở [module-json-anatomy.md](module-json-anatomy.md#checklist-khi-viết-modulejson) — dưới đây chỉ
+> là phần riêng của thiết kế giao diện.
+
+1. **Toolbar row**: shrink filters + v-spacer + permission-gated buttons
+2. **f-table**: fixed-header, item-class cho row highlight, item-key đúng — xem [ui-table-cell-patterns.md](ui-table-cell-patterns.md)
+3. **Dialogs**: luôn trong hidden-container, v-card[padding:0] + v-toolbar[dense flat] — xem [ui-dialog-patterns.md](ui-dialog-patterns.md)
+4. **menuChucNang**: định nghĩa trong data[], ref bằng t-menu trong headers — xem [ui-table-cell-patterns.md](ui-table-cell-patterns.md)
+5. **ctrl-update**: cho CRUD đơn giản, dialog thủ công cho form phức tạp
+6. **CALLBACK**: chaining array — reload → reset state → MESS
+7. **#PARENT**: set ngay đầu data[] trước các CALL startup — xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md)
+8. **Permission**: `v-if: "vueData.user.SystemRight>1"` cho admin-only sections

package/skills/fui-skill/references/ui-screenshot-review.md

@@ -0,0 +1,94 @@
+# Review giao diện qua ảnh chụp màn hình
+
+> File này sở hữu: **cách đọc và đánh giá ảnh chụp giao diện (user gửi hoặc từ `renderUI`)**.
+
+Áp dụng khi có **ảnh giao diện** để đánh giá, từ một trong hai nguồn:
+
+1. **User gửi ảnh chụp màn hình vào chat** — "xem giao diện này", "sao nhìn xấu vậy", "sửa lại cho đẹp", hoặc chỉ gửi ảnh kèm mô tả lỗi.
+2. **Screenshot từ `module_simulate({ renderUI: true })`** — `render.png` (inline), `render-full.png`, `render-dialog.jpg`.
+
+Nguyên tắc cốt lõi: **nhìn ảnh như một designer QA** — quét có hệ thống theo checklist bên dưới, và mỗi phát hiện phải map về **nguyên nhân cụ thể trong code** (controls[i] nào trong module.json, class/style nào, CSS nào trong header.html) kèm fix đề xuất. Đừng chỉ mô tả cảm tính "nhìn chưa đẹp".
+
+**BẮT BUỘC — phát hiện xong là phải SỬA, không phải chỉ ghi nhận.** Checklist A–D bên dưới không phải danh sách tham khảo: nhìn thấy chữ dính/chồng lấn (khoảng hở quá ít), control lệch hàng/không thẳng, khoảng trắng dư thừa bất thường giữa các control — đây là lỗi thẩm mỹ **phải xử lý trong cùng lượt**, y hệt một lỗi hiển thị cứng. "Đã ghi nhận vào báo cáo" không phải là "đã xong việc". Chỉ dừng lại hỏi user khi bản thân không chắc ý đồ thiết kế (vd không rõ hai khối có nên tách hàng hay không) — còn lại thì tự sửa rồi render lại đối chiếu (bước 4 dưới đây).
+
+---
+
+## Quy trình
+
+1. **Xác định bối cảnh** trước khi phán:
+   - App-mode (CRUD/quản lý — chuẩn thẩm mỹ `design_read("fui")`) hay Web-mode (landing — theo brand DESIGN.md đã chọn)?
+   - Desktop hay mobile? (ảnh hẹp/dọc → đánh giá theo chuẩn responsive)
+   - Có module.json tương ứng trong workspace không? (có → đối chiếu ảnh ↔ controls để chỉ đúng vị trí sửa; không → nhận xét trên ảnh + xin module.json nếu cần sửa)
+2. **Quét ảnh theo checklist A→D** (dưới) — ghi nhận từng phát hiện.
+3. **Báo cáo dạng bảng**: `Phát hiện | Mức độ (lỗi/cần sửa/gợi ý) | Vị trí trên ảnh | Nguyên nhân khả dĩ | Fix đề xuất`.
+4. **Tự sửa → render lại đối chiếu** (bắt buộc cho mọi phát hiện ở mục A/B, không chỉ lỗi cứng): nếu có workspace + Playwright, sửa module.json rồi `module_simulate({ renderUI: true })` (cùng viewport/device với ảnh gốc nếu đoán được) và so sánh screenshot mới với ảnh user gửi — lặp cho tới khi sạch. `renderUI` tự phát hiện text dính/chồng lấn (đối chiếu bounding-rect, xem mục A) và in vào DOM AUDIT kèm dòng "PHẢI sửa, không được bỏ qua" — thấy dòng đó thì sửa ngay trong lượt này, đừng để nguyên rồi báo cáo lại cho user quyết.
+
+Ảnh mờ/cắt/không đủ thông tin → hỏi user chụp lại vùng cụ thể, đừng đoán bừa.
+
+---
+
+## Checklist quét ảnh
+
+### A. Lỗi hiển thị cứng (bug — phải sửa)
+
+- Vùng trống bất thường: component không render (app rỗng, card trống, chart trắng/0-size)
+- Text lỗi lộ ra ngoài: `undefined`, `NaN`, `[object Object]`, message exception, key thay vì value
+- Tràn ngang: thanh cuộn ngang xuất hiện, phần tử bị cắt mép phải
+- Chữ/phần tử đè lên nhau, hoặc dính sát nhau tới mức đọc như liền một chữ (khoảng hở quá ít); label bị cắt cụt không chủ ý (truncate `...` ở chỗ không nên). `renderUI` dò được phần lớn ca này tự động (đối chiếu bounding-rect của các phần tử mang text, dòng `⚠ text dính/chồng lấn` trong DOM AUDIT) — nhưng đó chỉ là lưới an toàn, mắt vẫn phải tự quét thêm vì heuristic bỏ sót các ca không phải text thuần (icon chồng nút, ảnh chồng card...)
+- Ảnh vỡ (khung ảnh trống/icon broken), icon thiếu (ô vuông tofu — thường do font mdi chưa load hoặc sai tên icon)
+- Loading spinner đứng mãi (v_Loading không về false — thường API treo/lỗi init)
+
+### B. Bố cục, căn chỉnh, khoảng cách
+
+- **Thẳng hàng**: field cùng row thẳng baseline, cùng chiều cao (`dense`/`outlined` đồng bộ); các card/khối cùng hàng cùng chiều cao
+- **Căn trái/phải đúng ngữ nghĩa**: text căn trái; **số/tiền tệ trong bảng căn phải** (`t-num`); tiêu đề cột khớp hướng căn của data
+- **Vị trí nút chuẩn**: nút hành động chính của trang ở toolbar bên phải; trong dialog nút chính (Lưu/Đồng ý) nằm **phải** của `v-card-actions` (có `v-spacer` đẩy); không có nút "Đóng" thừa (D7)
+- **Hàng toolbar — nút phình / hở khoảng đều nhau**: triệu chứng đặc trưng của cột thiếu `shrink`. Nút rộng hơn hẳn chữ bên trong, các nút cách nhau những khoảng **bằng nhau**, và nhóm nút cuối **không sát mép phải** dù đã có `v-spacer` ⇒ các cột đó vẫn `flex-grow: 1` nên được chia phần trống y như spacer. Chuẩn: **mọi cột `"col": "shrink"`, trừ đúng `v-spacer`** — kể cả cột `w` rỗng ([controls-patterns.md](controls-patterns.md) §Hàng nhiều control). `module_validate` bắt được ca này trước khi phải nhìn ảnh
+- **Khoảng cách nhất quán**: padding/margin theo nhịp Vuetify (bội 4px — pa-2/ma-2...); không có khoảng hở to bất thường giữa các khối, không có khối dính sát mép màn hình
+- **Bảng data**: cuộn CHỈ trong bảng (bảng chính khai `":height": -16`), trang không có 2 thanh cuộn dọc lồng nhau, header bảng không trôi mất khi cuộn (D9)
+- **Cân đối grid**: các cột trong row có tỷ lệ hợp lý (Σw ≤ 12), không có cột bị bóp quá hẹp làm nội dung xuống dòng xấu
+
+### C. Màu sắc & phân cấp thị giác (App-mode đối chiếu `design_read("fui")`)
+
+- Đối chiếu bộ quy tắc D1–D9 của validator: toolbar dialog **cùng màu nền** thân (không color/dark); nút xóa màu **warning cam** (không đỏ/error); width dialog thuộc bộ 400/550/600/650/800
+- Một màn hình chỉ 1–2 màu nhấn; không tô màu tùy hứng vào card/nút phụ
+- Contrast đủ đọc (chữ xám nhạt trên nền trắng, chữ trên nền màu — nghi ngờ thì báo)
+- Trạng thái (chip/badge) dùng màu ngữ nghĩa nhất quán: success/warning/error cùng nghĩa ở mọi nơi
+
+### D. Mật độ & responsive
+
+- Mức `dense`/gọn đồng bộ toàn màn (không chỗ dày chỗ thưa)
+- Ảnh mobile: cột tự xuống dòng đúng, nút không tràn/không quá bé để bấm, font đọc được, bảng có phương án mobile (`mobile-breakpoint`)
+- `viewport-fit=cover` (mặc định của FUI): nội dung sát mép trên/dưới ở màn có notch → cần safe-area padding
+
+---
+
+## Map triệu chứng → nguyên nhân thường gặp
+
+| Triệu chứng trên ảnh | Nguyên nhân hay gặp | Fix |
+|---|---|---|
+| Trang có thanh cuộn dọc, bảng dài vô tận | f-table/f-sheet không khai `:height` → tự giãn theo số dòng | Thêm `":height": -16` (tự đo `rect.top`, fill tới đáy) |
+| Bảng hụt/tràn một khoảng cố định | `:height` cũ tính tay `"$( window ).height()-N"` không khớp toolbar thật | Thay bằng `":height": -16` |
+| Field trong form so le chiều cao | Trộn field có/không `dense`, có/không `hide-details` | Đồng bộ `outlined dense hide-details` cả form |
+| Số trong bảng căn trái | Cột thiếu `el: "t-num"` / align | Xem `component-table.md` |
+| Chart trắng | Container 0-height lúc chart init | Cho container `:height` cụ thể; renderUI audit "canvas 0-size" xác nhận |
+| Icon ô vuông | Sai tên `mdi-*` hoặc font chưa load | Kiểm tra tên icon; import materialdesignicons |
+| Dialog tràn màn hình / bé tẹo | width không thuộc bộ chuẩn | Bộ width 400/550/600/650/800 (D3) |
+| Nút chính lệch trái trong dialog | Thiếu `v-spacer` trong v-card-actions | Thêm v-spacer trước nút chính |
+| Khối dính mép màn hình | Thiếu page-container / pa-* | Xem `ui-layout-patterns.md` |
+
+---
+
+## Meta viewport mặc định của FUI (ảnh hưởng UI)
+
+Trang FUI mặc định đã có sẵn trong `<head>` (KHÔNG lặp lại trong header.html):
+
+```html
+<meta charset="UTF-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"/>
+```
+
+Hệ quả khi đánh giá/thiết kế:
+- `user-scalable=no, maximum-scale=1` — user **không pinch-zoom được** → font/nút phải đủ lớn ngay từ đầu trên mobile, không trông chờ zoom.
+- `width=device-width, initial-scale=1` — layout theo đúng CSS pixel của thiết bị; breakpoint Vuetify hoạt động chuẩn.
+- `viewport-fit=cover` — trang tràn vào vùng notch/home-indicator trên iOS → nội dung sát mép trên/dưới cần `env(safe-area-inset-*)` padding khi làm fullscreen/HTMLOnly.