@fui-org/fui-cli 1.3.2 → 2.0.0

package/skills/fui-skill/references/design-modes.md

@@ -1,85 +1,57 @@
 # Design System — App-mode vs Web-mode
 
-> File này sở hữu: **quyết định chế độ thẩm mỹ, giới hạn `border-radius`, vòng tích luỹ
-> `{projectId}/DESIGN.md`**. Về class/prop/style cụ thể được duyệt xem
-> [controls-styling-vocabulary.md](controls-styling-vocabulary.md). Về anatomy dialog/form chuẩn
-> dùng tool `design_read("fui")`.
+> Owns: **aesthetic mode decision, `border-radius` limits, the `{projectId}/DESIGN.md` accumulation loop**. Approved class/prop/style: [controls-styling-vocabulary.md](controls-styling-vocabulary.md). Standard dialog/form anatomy: `fui design read fui`.
 
-Trước khi viết bất kỳ `controls` nào, xác định module thuộc chế độ nào. Đây là quyết định đầu tiên
-và **cứng** — hai chế độ có bộ quy tắc thẩm mỹ riêng, không được vay mượn qua lại.
+Before writing any `controls`, decide the module's mode. This is the first, **hard** decision — each mode has its own aesthetic rules; never borrow across.
 
 ---
 
-## 1. Hai chế độ
-
-| | **App-mode** (mặc định) | **Web-mode** |
-|---|---|---|
-| Áp dụng cho | Phần mềm quản lý: CRUD, danh sách, form, dashboard nội bộ, phân quyền | Landing page, trang giới thiệu sản phẩm, trang công khai (thường `HTMLOnly: true`) |
-| Nguồn thẩm mỹ | **DUY NHẤT** `design_read("fui")` + `controls-styling-vocabulary.md` | Brand DESIGN.md (`design_list` → `design_read("<brand>")`) |
-| Brand DESIGN.md (nike, linear, bmw...) | **CẤM** — kể cả khi "chỉ lấy màu" | Được phép, chọn theo tone/ngành |
-| Style/class tự chế | **CẤM** (theo `controls-styling-vocabulary.md`) | Được phép trong `header.html` |
-| Ưu tiên component | `f-*` / `v-*` theo chuẩn FUI | Tự do HTML/CSS |
-
-**Tín hiệu nhận diện Web-mode**: `HTMLOnly: true` trong `_moduleInfo.json`, hoặc user mô tả
-"landing page / trang giới thiệu / trang chủ công khai". Mọi trường hợp còn lại → App-mode.
-Không chắc → **hỏi user**.
-
-⚠️ `HTMLOnly: true` không chỉ là tín hiệu thẩm mỹ: ở chế độ đó server **không nhúng sẵn** thư viện
-JS/CSS nào của V2/V3 (kể cả Vue, Vuetify, jQuery, lodash, MDI, `projectdefaultstyle.css`) — cần gì
-phải tự khai trong chính module. Xem [module-structure.md §HTMLOnly=true: KHÔNG có thư viện nào được
-nhúng sẵn](module-structure.md#htmlonlytrue-không-có-thư-viện-nào-được-nhúng-sẵn) **trước khi** viết
-thẻ đầu tiên.
-
-**Bắt buộc với App-mode**: trước khi viết/chỉnh sửa layout, dialog, form → nạp `design_read("fui")`
-(nếu chưa nạp trong phiên) để lấy anatomy chuẩn (dialog `v-dialog` phong cách f-dialog, form
-floating label, bảng màu/icon), đồng thời đọc `controls-styling-vocabulary.md`. AI phải hoàn tất bước
-đọc này **trước khi phác thảo hoặc viết control**, không vừa thiết kế vừa đoán quy tắc từ trí nhớ.
-
-Trước khi bắt đầu thiết kế, tự xác nhận đã hiểu ba nhóm quy tắc giao diện cốt lõi trong các file chủ
-sở hữu: kích thước icon và từ vựng styling (`controls-styling-vocabulary.md`), anatomy/action của
-dialog (`design_read("fui")` + `ui-dialog-patterns.md`), và canh dọc control trong một hàng
-(`controls-patterns.md` §Canh giữa control theo chiều dọc). Nếu task có dialog thì phải đọc thêm
-`ui-dialog-patterns.md` trước khi phác thảo dialog.
+## 1. The two modes
 
----
+|                                        | **App-mode** (default)                                                    | **Web-mode**                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Applies to                             | Management software: CRUD, lists, forms, internal dashboards, permissions | Landing pages, product intros, public pages (usually `HTMLOnly: true`) |
+| Aesthetic source                       | **ONLY** `fui design read fui` + `controls-styling-vocabulary.md`         | Brand DESIGN.md (`fui design list` → `fui design read <brand>`)        |
+| Brand DESIGN.md (nike, linear, bmw...) | **FORBIDDEN** — even "just the colors"                                    | Allowed, pick by tone/industry                                         |
+| Custom style/class                     | **FORBIDDEN** (per `controls-styling-vocabulary.md`)                      | Allowed in `header.html`                                               |
+| Component preference                   | `f-*` / `v-*` per FUI standard                                            | Free HTML/CSS                                                          |
+
+**Web-mode signals**: `HTMLOnly: true` in `_moduleInfo.json`, or user says "landing page / intro page / public home page". Everything else → App-mode. Unsure → **ask the user**.
+
+⚠️ `HTMLOnly: true` is not just an aesthetic signal: the server then embeds **no** V2/V3 JS/CSS library (not Vue, Vuetify, jQuery, lodash, MDI, `projectdefaultstyle.css`) — declare everything needed in the module itself. Read [module-structure.md §HTMLOnly=true: no library is embedded](module-structure.md#htmlonlytrue-no-library-is-embedded) **before** writing the first tag.
 
-## 2. Override theo project — `{projectId}/DESIGN.md`
+**Mandatory in App-mode**: before writing/editing layout, dialog or form, load `fui design read fui` (if not loaded this session) for the standard anatomy (f-dialog-style `v-dialog`, floating-label form, color/icon palette), and read `controls-styling-vocabulary.md`. Finish this reading **before sketching or writing controls** — never design while guessing rules from memory.
 
-Nếu `{projectId}/DESIGN.md` tồn tại trong workspace → file đó **ghi đè** quy tắc cùng chủ đề của
-chế độ đang dùng (những gì không đề cập vẫn theo chuẩn chung). **Luôn kiểm tra file này trước khi
-thiết kế.**
+Before designing, confirm the three core UI rule groups from their owner files: icon sizes and styling vocabulary (`controls-styling-vocabulary.md`), dialog anatomy/actions (`fui design read fui` + `ui-dialog-patterns.md`), and vertical alignment of controls in a row (`controls-patterns.md` §Vertical centering). If the task has a dialog, also read `ui-dialog-patterns.md` before sketching it.
 
 ---
 
-## 3. Vòng tích luỹ chuẩn thiết kế (BẮT BUỘC)
+## 2. Per-project override — `{projectId}/DESIGN.md`
+
+If `{projectId}/DESIGN.md` exists in the workspace, it **overrides** same-topic rules of the active mode (unmentioned topics follow the common standard). **Always check it before designing.**
+
+---
 
-Khi user góp ý/chê một chi tiết UI ("dialog phải...", "nút này màu...", "đừng dùng..."):
+## 3. Design-rule accumulation loop (MANDATORY)
 
-1. Sửa module theo góp ý.
-2. **Ghi ngay quy tắc đó vào `{projectId}/DESIGN.md`** (tạo file nếu chưa có — theo template ở cuối
-   `design_read("fui")`), diễn đạt thành **quy tắc tổng quát + ví dụ JSON đúng/sai**, không chỉ ghi
-   lại tình huống cụ thể.
-3. Nếu quy tắc rõ ràng áp dụng cho MỌI project (không riêng project này) → nói với user: "quy tắc
-   này nên đưa vào chuẩn chung `fui/DESIGN.md`" và đề xuất nội dung — **chỉ user quyết định** cập
-   nhật chuẩn chung.
+When the user critiques a UI detail ("dialog must...", "this button's color...", "don't use..."):
 
-Nhờ vòng này, góp ý của user không bị mất sau phiên chat — lần thiết kế sau tự động tuân theo.
+1. Fix the module per the feedback.
+2. **Immediately write the rule into `{projectId}/DESIGN.md`** (create it if missing — use the template at the end of `fui design read fui`), phrased as a **general rule + correct/incorrect JSON examples**, not just the specific incident.
+3. If the rule clearly applies to EVERY project → tell the user "this rule should go into the common standard `fui/DESIGN.md`" and propose the content — **only the user decides** to update the common standard.
 
 ---
 
-## 4. Giới hạn `border-radius`
+## 4. `border-radius` limits
 
-Áp dụng cho **MỌI brand/style, kể cả khi DESIGN.md của brand đề xuất giá trị lớn hơn**:
+Apply to **EVERY brand/style, even when a brand DESIGN.md suggests larger values**:
 
-| Loại khung | `border-radius` tối đa |
-|---|---|
-| Khung lớn tổng quát (card container, dialog, section wrapper, panel chính) | `12px` |
-| Khung vừa (button lớn, input group, panel con, toolbar) | `8px` |
-| Khung nhỏ (button nhỏ, chip, badge, tag, icon container) | `6px` |
+| Frame type                                                         | Max `border-radius` |
+| ------------------------------------------------------------------ | ------------------- |
+| Large frames (card container, dialog, section wrapper, main panel) | `12px`              |
+| Medium frames (large button, input group, sub-panel, toolbar)      | `8px`               |
+| Small frames (small button, chip, badge, tag, icon container)      | `6px`               |
 
-Nếu brand DESIGN.md đề xuất `border-radius` lớn hơn mức tương ứng ở trên (ví dụ các brand có bo
-tròn mạnh như Airbnb, Notion, Nike...) → **hạ xuống mức tối đa cho phép**, không áp dụng nguyên giá
-trị gốc.
+If a brand DESIGN.md suggests a larger radius (heavily rounded brands like Airbnb, Notion, Nike...) → **lower it to the allowed max**; never use the original value.
 
-**Ngoại lệ**: phần tử tròn hoàn toàn (avatar, icon button dạng chấm tròn) dùng `border-radius: 50%`
-— không thuộc phạm vi giới hạn này.
+**Exception**: fully round elements (avatar, round dot icon button) use `border-radius: 50%` — outside these limits.