@fui-org/fui-cli 2.1.3 → 2.2.0

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

@@ -1,95 +1,95 @@
-# UI review from screenshots
-
-> Owns: **reading and assessing UI screenshots (user-sent or from `--render`)**.
-
-Sources: (1) **user screenshot in chat** ("why is it ugly", "make it nicer", or an image + bug description); (2) **`fui module simulate --render`** — `render.png` (inline), `render-full.png`, `render-dialog.jpg`.
-
-Act as design QA: scan with the checklist; map every finding to a **concrete code cause** (controls[i] in module.json, class/style, CSS in header.html) + fix. No vague "doesn't look good".
-
-**MANDATORY — FIX findings, don't just report them.** Stuck/overlapping text (too little gap), misaligned controls, abnormal whitespace between controls are bugs **to fix in the same turn**, like hard rendering bugs. "Noted in the report" ≠ done. Ask the user only when design intent is unclear (e.g. should two blocks be on separate rows); otherwise fix and re-render (step 4).
-
----
-
-## Workflow
-
-1. **Establish context** first:
-   - App-mode (CRUD/admin — aesthetic standard `fui design read fui`) or Web-mode (landing — chosen brand DESIGN.md)?
-   - Desktop or mobile? (narrow/portrait image → judge by responsive standards)
-   - module.json in workspace? Yes → cross-check image ↔ controls to pinpoint the fix; no → comment on the image, ask for module.json if a fix is needed
-2. **Scan with checklist A→D**, record each finding.
-3. **Report as a table**: `Finding | Severity (bug/should fix/suggestion) | Location in image | Likely cause | Proposed fix`.
-4. **Fix → re-render → compare** (required for every A/B finding): with workspace + Playwright, edit module.json, run `fui module simulate --render` (same viewport/device as the original if guessable), compare with the user's image; repeat until clean. `--render` auto-detects stuck/overlapping text (bounding rects, see A) and prints it in DOM AUDIT with "PHẢI sửa, không được bỏ qua" — fix it this turn; don't hand it to the user.
-
-Blurry/cropped/insufficient image → ask the user to recapture the specific area; don't guess.
-
----
-
-## Scan checklist
-
-### A. Hard rendering bugs (must fix)
-
-- Abnormal empty area: component didn't render (empty app, blank card, white/0-size chart)
-- Leaked error text: `undefined`, `NaN`, `[object Object]`, exception messages, keys instead of values
-- Horizontal overflow: horizontal scrollbar, elements clipped at the right edge
-- Overlapping text/elements, or so close they read as one word; unintended truncation (`...`). `--render` catches most (line `⚠ text dính/chồng lấn` in DOM AUDIT) — only a safety net; still scan by eye, the heuristic misses non-text cases (icon over button, image over card...)
-- Broken image (empty frame/broken icon), missing icon (tofu square — usually mdi font not loaded or wrong icon name)
-- Spinner forever (v_Loading never returns to false — usually a hung API/init error)
-
-### B. Layout, alignment, spacing
-
-- **Alignment**: fields in a row share baseline and height (consistent `dense`/`outlined`); cards/blocks in a row share height
-- **Semantic alignment**: text left; **numbers/currency in tables right** (`t-num`); column header matches data alignment
-- **Button placement**: page primary action in the toolbar on the right; in a dialog the primary button (Lưu/Đồng ý) sits **right** in `v-card-actions` (pushed by `v-spacer`); no redundant "Đóng" button (D7)
-- **Toolbar row — bloated buttons / equal gaps** = columns missing `shrink`: buttons much wider than their text, **equal** gaps, trailing group **not flush right** despite `v-spacer` ⇒ columns still `flex-grow: 1`, sharing free space like the spacer. Standard: **every column `"col": "shrink"` except `v-spacer`** — including empty-`w` columns ([controls-patterns.md](controls-patterns.md) §Toolbar row). `fui module validate` catches this before any screenshot
-- **Consistent spacing**: Vuetify rhythm (multiples of 4px — pa-2/ma-2...); no abnormally large gaps between blocks, no blocks touching the screen edge
-- **Data tables**: scroll ONLY inside the table (main table declares `":height": -16`), no two nested vertical page scrollbars, table header stays visible on scroll (D9)
-- **Grid balance**: sensible column ratios in a row (Σw ≤ 12), no column squeezed so narrow content wraps badly
-
-### C. Color & visual hierarchy (App-mode vs `fui design read fui`)
-
-- Validator rules D1–D9: dialog toolbar **same background** as body (no color/dark); delete button **warning orange** (not red/error); dialog width in 400/550/600/650/800
-- 1–2 accent colors per screen; no arbitrary color on cards/secondary buttons
-- Readable contrast (light grey on white, text on colored backgrounds — report if doubtful)
-- Status (chip/badge) semantic colors consistent: success/warning/error mean the same everywhere
-
-### D. Density & responsive
-
-- Consistent `dense`/compact level across the screen (no dense-here, sparse-there)
-- Mobile image: columns wrap correctly, buttons don't overflow and aren't too small to tap, readable font, tables have a mobile plan (`mobile-breakpoint`)
-- `viewport-fit=cover` (FUI default): content at top/bottom edges on notched screens → needs safe-area padding
-
----
-
-## Symptom → common cause
-
-| Symptom                                   | Common cause                                                                          | Fix                                                                                |
-| ----------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Page has vertical scroll, endless table   | f-table/f-sheet without `:height` → grows with row count                              | Add `":height": -16` (measures `rect.top`, fills to bottom)                        |
-| Table short/overflowing by a fixed amount | Old hand-computed `:height` `"$( window ).height()-N"` doesn't match the real toolbar | Replace with `":height": -16`                                                      |
-| Form fields of uneven height              | Mixed with/without `dense`, `hide-details`                                            | Use `outlined dense hide-details` across the form                                  |
-| Numbers left-aligned in table             | Column missing `el: "t-num"` / align                                                  | See `component-table.md`                                                           |
-| Blank chart                               | Container 0-height at chart init                                                      | Give the container a concrete `:height`; `--render` audit "canvas 0-size" confirms |
-| Square icon                               | Wrong `mdi-*` name or font not loaded                                                 | Check icon name; import materialdesignicons                                        |
-| Dialog overflowing / tiny                 | Non-standard width                                                                    | Widths 400/550/600/650/800 (D3)                                                    |
-| Primary button left in dialog             | Missing `v-spacer` in v-card-actions                                                  | Add v-spacer before the primary button                                             |
-| Block touching screen edge                | Missing page-container / pa-*                                                         | See `ui-layout-patterns.md`                                                        |
-
----
-
-## FUI default meta viewport (affects UI)
-
-FUI pages already include in `<head>` (do NOT repeat in 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"
-/>
-```
-
-Consequences:
-
-- `user-scalable=no, maximum-scale=1` — **no pinch-zoom** → fonts/buttons must be large enough on mobile from the start.
-- `width=device-width, initial-scale=1` — layout in true device CSS pixels; Vuetify breakpoints work normally.
-- `viewport-fit=cover` — page extends into iOS notch/home-indicator → content at top/bottom edges needs `env(safe-area-inset-*)` padding for fullscreen/HTMLOnly.
+# UI review from screenshots
+
+> Owns: **reading and assessing UI screenshots (user-sent or from `--render`)**.
+
+Sources: (1) **user screenshot in chat** ("why is it ugly", "make it nicer", or an image + bug description); (2) **`fui module simulate --render`** — `render.png`, `render-full.png`, `render-dialog.jpg` in `{moduleDir}/_preview/`. The report prints their paths and attaches nothing: open each file.
+
+Act as design QA: scan with the checklist; map every finding to a **concrete code cause** (controls[i] in module.json, class/style, CSS in header.html) + fix. No vague "doesn't look good".
+
+**MANDATORY — FIX findings, don't just report them.** Stuck/overlapping text (too little gap), misaligned controls, abnormal whitespace between controls are bugs **to fix in the same turn**, like hard rendering bugs. "Noted in the report" ≠ done. Ask the user only when design intent is unclear (e.g. should two blocks be on separate rows); otherwise fix and re-render (step 4).
+
+---
+
+## Workflow
+
+1. **Establish context** first:
+   - App-mode (CRUD/admin — aesthetic standard `fui design read fui`) or Web-mode (landing — chosen brand DESIGN.md)?
+   - Desktop or mobile? (narrow/portrait image → judge by responsive standards)
+   - module.json in workspace? Yes → cross-check image ↔ controls to pinpoint the fix; no → comment on the image, ask for module.json if a fix is needed
+2. **Scan with checklist A→D**, record each finding.
+3. **Report as a table**: `Finding | Severity (bug/should fix/suggestion) | Location in image | Likely cause | Proposed fix`.
+4. **Fix → re-render → compare** (required for every A/B finding): with workspace + Playwright, edit module.json, run `fui module simulate --render` (same viewport/device as the original if guessable), compare with the user's image; repeat until clean. `--render` auto-detects stuck/overlapping text (bounding rects, see A) and prints it in DOM AUDIT as `⚠ text collisions (visual; MUST fix)` — fix it this turn; don't hand it to the user.
+
+Blurry/cropped/insufficient image → ask the user to recapture the specific area; don't guess.
+
+---
+
+## Scan checklist
+
+### A. Hard rendering bugs (must fix)
+
+- Abnormal empty area: component didn't render (empty app, blank card, white/0-size chart)
+- Leaked error text: `undefined`, `NaN`, `[object Object]`, exception messages, keys instead of values
+- Horizontal overflow: horizontal scrollbar, elements clipped at the right edge
+- Overlapping text/elements, or so close they read as one word; unintended truncation (`...`). `--render` catches most (line `⚠ text collisions` in DOM AUDIT) — only a safety net; still scan by eye, the heuristic misses non-text cases (icon over button, image over card...)
+- Broken image (empty frame/broken icon), missing icon (tofu square — usually mdi font not loaded or wrong icon name)
+- Spinner forever (v_Loading never returns to false — usually a hung API/init error)
+
+### B. Layout, alignment, spacing
+
+- **Alignment**: fields in a row share baseline and height (consistent `dense`/`outlined`); cards/blocks in a row share height
+- **Semantic alignment**: text left; **numbers/currency in tables right** (`t-num`); column header matches data alignment
+- **Button placement**: page primary action in the toolbar on the right; in a dialog the primary button (Lưu/Đồng ý) sits **right** in `v-card-actions` (pushed by `v-spacer`); no redundant "Đóng" button (D7)
+- **Toolbar row — bloated buttons / equal gaps** = columns missing `shrink`: buttons much wider than their text, **equal** gaps, trailing group **not flush right** despite `v-spacer` ⇒ columns still `flex-grow: 1`, sharing free space like the spacer. Standard: **every column `"col": "shrink"` except `v-spacer`** — including empty-`w` columns ([controls-patterns.md](controls-patterns.md) §Toolbar row). `fui module validate` catches this before any screenshot
+- **Consistent spacing**: Vuetify rhythm (multiples of 4px — pa-2/ma-2...); no abnormally large gaps between blocks, no blocks touching the screen edge
+- **Data tables**: scroll ONLY inside the table (main table declares `":height": -16`), no two nested vertical page scrollbars, table header stays visible on scroll (D9)
+- **Grid balance**: sensible column ratios in a row (Σw ≤ 12), no column squeezed so narrow content wraps badly
+
+### C. Color & visual hierarchy (App-mode vs `fui design read fui`)
+
+- Validator rules D1–D9: dialog toolbar **same background** as body (no color/dark); delete button **warning orange** (not red/error); dialog width in 400/550/600/650/800
+- 1–2 accent colors per screen; no arbitrary color on cards/secondary buttons
+- Readable contrast (light grey on white, text on colored backgrounds — report if doubtful)
+- Status (chip/badge) semantic colors consistent: success/warning/error mean the same everywhere
+
+### D. Density & responsive
+
+- Consistent `dense`/compact level across the screen (no dense-here, sparse-there)
+- Mobile image: columns wrap correctly, buttons don't overflow and aren't too small to tap, readable font, tables have a mobile plan (`mobile-breakpoint`)
+- `viewport-fit=cover` (FUI default): content at top/bottom edges on notched screens → needs safe-area padding
+
+---
+
+## Symptom → common cause
+
+| Symptom                                   | Common cause                                                                          | Fix                                                                                |
+| ----------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Page has vertical scroll, endless table   | f-table/f-sheet without `:height` → grows with row count                              | Add `":height": -16` (measures `rect.top`, fills to bottom)                        |
+| Table short/overflowing by a fixed amount | Old hand-computed `:height` `"$( window ).height()-N"` doesn't match the real toolbar | Replace with `":height": -16`                                                      |
+| Form fields of uneven height              | Mixed with/without `dense`, `hide-details`                                            | Use `outlined dense hide-details` across the form                                  |
+| Numbers left-aligned in table             | Column missing `el: "t-num"` / align                                                  | See `component-table.md`                                                           |
+| Blank chart                               | Container 0-height at chart init                                                      | Give the container a concrete `:height`; `--render` audit "canvas 0-size" confirms |
+| Square icon                               | Wrong `mdi-*` name or font not loaded                                                 | Check icon name; import materialdesignicons                                        |
+| Dialog overflowing / tiny                 | Non-standard width                                                                    | Widths 400/550/600/650/800 (D3)                                                    |
+| Primary button left in dialog             | Missing `v-spacer` in v-card-actions                                                  | Add v-spacer before the primary button                                             |
+| Block touching screen edge                | Missing page-container / pa-*                                                         | See `ui-layout-patterns.md`                                                        |
+
+---
+
+## FUI default meta viewport (affects UI)
+
+FUI pages already include in `<head>` (do NOT repeat in 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"
+/>
+```
+
+Consequences:
+
+- `user-scalable=no, maximum-scale=1` — **no pinch-zoom** → fonts/buttons must be large enough on mobile from the start.
+- `width=device-width, initial-scale=1` — layout in true device CSS pixels; Vuetify breakpoints work normally.
+- `viewport-fit=cover` — page extends into iOS notch/home-indicator → content at top/bottom edges needs `env(safe-area-inset-*)` padding for fullscreen/HTMLOnly.