@godxjp/ui 23.4.1 → 23.4.3

package/scripts/consumer-rule.md

@@ -1,6 +1,9 @@
 # @godxjp/ui
 
-> **Tệp này do gói `@godxjp/ui` sở hữu và bị GHI ĐÈ mỗi lần nâng cấp.**
+> **Tệp này do gói `@godxjp/ui` sở hữu.** Nội dung được ghi lại khi luật trong gói đổi (thường
+> qua postinstall sau `npm i`, trừ khi `.npmrc` có `ignore-scripts=true`). Khi đó chạy
+> `npx @godxjp/ui sync-rules`. Dấu `<!-- godxjp-ui:version -->` luôn được đồng bộ với phiên bản
+> gói đang cài — kể cả khi thân tệp không đổi giữa hai bản.
 > Đừng sửa ở đây — luật của riêng kho thuộc về một tệp khác trong `.ai/rules/`,
 > và index sẽ nạp cả hai. (Khác với `.claude/skills/.../SKILL.md`, nơi mục §8
 > trở đi là của kho và được giữ lại.)
@@ -9,11 +12,12 @@
 `docs/CONSUMER-RULES.md` (10 luật) và, với kho chuột bạch, ở
 `.claude/skills/godx-ui-guinea-pig/SKILL.md`.
 
-## Nạp style: HAI lối vào, và lối thứ hai không chở font
+## Nạp style: BA lối vào, và hai lối sau không chở font
 
 ```css
-@import "@godxjp/ui/styles";      /* mọi layer + Noto Sans JP / M PLUS 2 đóng gói sẵn */
+@import "@godxjp/ui/styles"; /* mọi layer + Noto Sans JP / M PLUS 2 đóng gói sẵn */
 @import "@godxjp/ui/styles/core"; /* CÙNG các layer ấy, KHÔNG một @font-face nào */
+@import "@godxjp/ui/styles/core-with-fallbacks"; /* core + 6 khối local()-only, vẫn 0 byte mạng */
 ```
 
 Chọn `core` khi kho tự lo mặt chữ, hoặc khi không muốn chở font: `@fontsource` cắt
@@ -21,9 +25,18 @@ Noto Sans JP thành hàng trăm lát `unicode-range`, và trình duyệt chỉ b
 SAU khi đã dựng bố cục — một consumer đo được **737 lát / 13 MB**, gấp bảy lần toàn bộ
 JavaScript của họ, cộng ~8 vòng tải mỗi lần chuyển màn.
 
-`core` không phải cherry-pick: nó là một trong hai lối vào được hỗ trợ, và thứ tự layer
-vẫn nguyên vẹn. Cherry-pick từng layer riêng lẻ thì vẫn cấm — đó là thứ làm vỡ hợp đồng
-thứ tự, không phải việc chọn lối vào.
+Lối thứ ba dành cho kho **tự cấp Noto Sans JP** (next/font, self-host) mà vẫn muốn cửa
+sổ swap không đội hình: nó chở đúng 6 `@font-face` metric-matched, `src` toàn `local()`
+nên **không tải byte nào**. Nhớ tự xếp tên họ chữ ngay sau mặt chữ của bạn:
+`--font-sans-base: "Noto Sans JP", "Noto Sans JP Fallback", system-ui, sans-serif;`
+
+`core` giữ `@font-face` = **0** và đó là lời hứa đo được —
+`grep -c '@font-face' node_modules/@godxjp/ui/dist/styles/core.css` → `0`. Vì vậy các
+fallback nằm ở entry riêng chứ không nhét vào `core`.
+
+Không lối nào trong ba là cherry-pick: cả ba đều được hỗ trợ và thứ tự layer vẫn nguyên
+vẹn. Cherry-pick từng layer riêng lẻ thì vẫn cấm — đó là thứ làm vỡ hợp đồng thứ tự,
+không phải việc chọn lối vào.
 
 ## Bố cục chuẩn của platform: BA CỘT, và ba cột là BA PHẠM VI
 
@@ -66,24 +79,69 @@ Slack thì đặt lại **một dòng**, không fork `.app-nav-rail`.
 Hỏi MCP `godxjp-ui` (`search_components`, `get_component`). Đo được trong một
 ngày: năm thứ cần đều ĐÃ CÓ và vẫn bị dựng lại bằng thứ khác —
 
-| Cần                                      | Đã có                 |
-| ---------------------------------------- | --------------------- |
-| đường kẻ chạm mép Card                   | `<CardContent flush>` |
-| header có kẻ khi thân là danh sách flush | `<CardHeader banded>` |
-| một hàng LÀ liên kết (thay cho nút rời)  | `<ListRow asChild>`   |
-| kẻ ô từng ngày trong lịch                | `<Calendar bordered>` |
-| dải giữa hai vùng, tự kẻ theo VỊ TRÍ     | `<CardBar>`           |
+| Cần                                             | Đã có                                                                              |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------- |
+| đường kẻ chạm mép Card                          | `<CardContent flush>`                                                              |
+| header có kẻ khi thân là danh sách flush        | `<CardHeader banded>`                                                              |
+| một hàng LÀ liên kết (thay cho nút rời)         | `<ListRow asChild>`                                                                |
+| kẻ ô từng ngày trong lịch                       | `<Calendar bordered>`                                                              |
+| dải giữa hai vùng, tự kẻ theo VỊ TRÍ            | `<CardBar>` (`border` để ép khi xếp chồng)                                         |
+| chip "điều kiện đang bật" có dấu × để bỏ        | `<Badge onRemove>` — KHÔNG phải `TagInput`                                         |
+| dải tab nằm TRONG đầu Card                      | `<Card tabList activeTabKey onTabChange>`                                          |
+| tiêu đề / đoạn văn / liên kết trong văn bản     | `<Title>` · `<Paragraph>` · `<Link>` (`Text` 33 prop)                              |
+| nút nổi góc màn (quay lên đầu, hành động nhanh) | `<FloatButton>`                                                                    |
+| khung xương của một FORM khi đang tải           | `<SkeletonForm>`                                                                   |
+| ô màu chỉ để xem, màu do NGƯỜI DÙNG chọn        | `<Swatch>`                                                                         |
+| ảnh đại diện của một tệp / bản xem trước        | `<Thumbnail>`                                                                      |
+| danh sách "có gì trong gói này"                 | `<FeatureList>`                                                                    |
+| panel kéo giãn được (chia đôi màn)              | `<DraggablePanel>`                                                                 |
+| màn hội thoại AI                                | `<Welcome>` · `<Conversations>` · `<Attachments>` · `<ThoughtChain>` · `<Actions>` |
 
 Lỗi không phải "đoán sai tên prop" mà là **cho rằng nó không tồn tại nên không
 hỏi**.
 
-## Catalog chở PROP, không chở LUẬT BỐ CỤC
+## Dialog và AlertDialog là MỘT họ — `variant` là lối chuẩn
 
-`CardBar` trong manifest có đúng một prop (`extra`) — không dòng nào nói nó tự
-kẻ theo vị trí (đầu: kẻ dưới · cuối: kẻ trên · giữa: cả hai). Luật ấy chỉ nằm
-trong chú thích `node_modules/@godxjp/ui/src/styles/card-layout.css`.
+Đừng với tay sang 12 export `AlertDialog*` nữa. Chúng **vẫn chạy y như cũ** (gỡ
+là breaking change) nhưng là **LỐI CŨ**: đo được 26 export với **12 cặp trùng
+tên** và **0** phần chỉ `AlertDialog` mới có. antd — thẩm quyền bề mặt prop của
+gói này — chỉ có MỘT `Modal`, và mức nguy hiểm ở đó là một PROP.
+
+```tsx
+<DialogContent variant="destructive">   {/* thay cho <AlertDialogContent> */}
+```
 
-**Làm bố cục trong một component của DS → mở tệp `*-layout.css` của nó ra đọc.**
+Một prop ấy quyết định ba thứ đi cùng nhau: `role="alertdialog"`, click ra ngoài
+KHÔNG đóng, nút chính nhấn mạnh destructive (và ✕ mặc định tắt). Esc VẪN đóng —
+y như `AlertDialogContent` trước nay. Đặt `variant` ở `DialogRoot` thì cả cây kế
+thừa.
+
+## antd là CHUẨN — thiếu gì thì port 100%, đừng tự thiết kế
+
+`docs/DESIGN-AUTHORITY.md` của gói: **nơi antd đặt tên cho một năng lực, gói này
+lấy nguyên tên và nguyên ngữ nghĩa của antd.** Một năng lực còn thiếu được port
+từ antd **100% TRƯỚC** — tên, prop, ngữ nghĩa — rồi mới cải tiến. Không thiết kế
+lại trước, không port một nửa.
+
+Nghĩa là với consumer: thấy thiếu prop thì **mở issue kèm tên antd của nó**
+(`sorter`, `closable`, `okType`…), đừng đề xuất một cái tên mới và đừng tự vẽ
+lại bằng class tiện ích. Ba trục cố ý lệch khỏi antd đều đã ghi lý do trong
+DESIGN-AUTHORITY (logical thay cho `left/right`, từ vựng giá trị của gói này,
+`density` thay cho `size`) — lệch thêm thì phải viết ra ở đó.
+
+## Catalog giờ chở CẢ luật bố cục — nhưng phải hỏi mới có
+
+Mục này từng nói "catalog chở PROP, không chở LUẬT BỐ CỤC", với `CardBar` làm
+bằng chứng: một prop (`extra`), không dòng nào nói nó tự kẻ theo vị trí. **Bằng
+chứng ấy đã hết đúng.** `CardBar` nay có 6 prop, trong đó `border` (`"none" |
+"block-start" | "block-end" | "both"`) ép được đường kẻ khi xếp chồng, và cả
+`Card` lẫn `CardBar` trong catalog đều nói ra luật vị trí (đầu: kẻ dưới · cuối:
+kẻ trên · giữa: cả hai).
+
+Nên luật hiện hành là: **hỏi `get_component` trước** — nay nó thường trả lời cả
+hình dạng lẫn luật. Còn khi `usage`/`description` im lặng về bố cục thì mới mở
+`node_modules/@godxjp/ui/src/styles/*-layout.css` của component ấy ra đọc; chú
+thích trong đó vẫn là bản đầy đủ nhất.
 
 ## Card không lồng Card
 

package/scripts/guinea-pig-skill.md

@@ -101,6 +101,28 @@ Thứ tự ưu tiên, chỉ tiến khi bước trước thật sự không diễ
 **dùng → ghép → thêm prop vào component đã có → tạo component mới.**
 Một prop nữa hơn một component nữa.
 
+**Và TÊN không phải của bạn — nó là của antd.** `docs/DESIGN-AUTHORITY.md` (mục
+"The PROP SURFACE of a component is antd's too"): **nơi antd đặt tên cho một năng
+lực, kho này lấy nguyên tên và nguyên ngữ nghĩa của antd. Một năng lực còn thiếu
+được port từ antd 100% TRƯỚC — tên, prop, ngữ nghĩa — rồi mới cải tiến. Không
+thiết kế lại trước, và không port một nửa.**
+
+Đây là luật mới nhất và là luật hay bị bỏ qua nhất, vì nó nghe như lời khuyên.
+Cái giá của việc bỏ qua đã đo được: `DataTable` mọc `pin: "end"` nơi antd có
+`fixed`, `sortable: true` nơi antd có `sorter`, và không có câu trả lời nào cho
+filter/expandable — mỗi lần một người quyết một kiểu. Cùng hình dạng lỗi:
+`Dialog` + `AlertDialog` từng là 26 export với **12 cặp trùng tên** và **0** phần
+chỉ `AlertDialog` mới có, trong khi antd chỉ có MỘT `Modal` (nguy hiểm là một
+PROP, `okType`). Nay là một họ, `variant` là lối chuẩn, 12 export cũ ở lại vì gỡ
+là breaking. Và cả họ Ant Design X từng tới nửa vời — thiếu `Conversations`,
+`Attachments`, `ThoughtChain`, `Welcome`, `Actions`, nay đã đủ.
+
+Ba chỗ cố ý lệch khỏi antd (logical thay `left/right`, từ vựng giá trị của kho
+này, `density` thay `size`) đều **ghi lý do trong DESIGN-AUTHORITY**. Lệch thêm
+thì phải viết vào đó, không lệch lặng lẽ. Và đọc bề mặt antd từ **type đã cài ở
+một checkout khác**, không từ trí nhớ — `antd` đã bị gỡ khỏi devDependencies của
+kho này từ 20.0.0 và `check:no-antd-runtime` canh cho nó không quay lại.
+
 ### Bước 4 — Kiểm bằng tarball TRƯỚC khi phát hành
 
 Đây là bước làm cho "vừa làm vừa trải nghiệm" thành thật. Đừng phát hành rồi
@@ -303,15 +325,22 @@ không tồn tại nên không hỏi**.
 Trước khi viết bất kỳ bố cục nào: `search_components` + `get_component`. Rẻ hơn
 mọi lần sửa sau.
 
-**Nhưng catalog chở PROP, không chở LUẬT BỐ CỤC** — và đó là một khoảng trống
-thật của catalog, không chỉ là lỗi của người dùng nó. Ví dụ đo được: `CardBar`
-trong manifest có đúng một prop (`extra`), không dòng nào nói nó **tự lấy đường
-kẻ theo VỊ TRÍ** — đầu thì kẻ dưới, cuối thì kẻ trên, ở giữa thì cả hai. Luật ấy
-chỉ nằm trong chú thích của `src/styles/card-layout.css`, cùng chỗ định nghĩa hai
-nhịp `section` (header phẳng) và `band` (header có kẻ).
-
-Nên khi làm bố cục bên trong một component của DS: **mở tệp `*-layout.css` của
-nó ra đọc**. Một agent hỏi MCP đúng cách vẫn sẽ không biết những luật này.
+**Catalog từng chở PROP mà không chở LUẬT BỐ CỤC — và ví dụ ấy nay đã được vá,
+nên đừng trích nó nữa.** Bản trước của mục này viết: `CardBar` trong manifest có
+đúng một prop (`extra`), không dòng nào nói nó tự lấy đường kẻ theo VỊ TRÍ. Đo
+lại hôm nay: `CardBar` có **6 prop**, trong đó `border` (`"none" | "block-start"
+| "block-end" | "both"`) ép được đường kẻ khi xếp chồng, và luật vị trí (đầu: kẻ
+dưới · cuối: kẻ trên · giữa: cả hai) nằm **trong chính catalog** — ở `usage` của
+`CardBar` lẫn `description` của `Card`.
+
+Bài học còn lại vẫn thật, chỉ đổi hình: một luật bố cục **có thể** chỉ sống
+trong chú thích CSS, và không có cổng nào bắt nó phải lên catalog. Nên:
+
+1. Hỏi `get_component` trước — nay nó thường trả lời cả hình dạng lẫn luật.
+2. `usage`/`description` im lặng về bố cục → mở `src/styles/*-layout.css` của
+   component ấy ra đọc (chỗ định nghĩa hai nhịp `section` và `band` chẳng hạn).
+3. Là chuột bạch, khi bước 2 phải dùng tới, đó là **khoảng trống catalog** — đưa
+   luật ấy lên `usage` trong cùng PR, theo §4. Đó là cách `CardBar` được vá.
 
 ## 6. Thứ KHÔNG đẩy lên DS
 

package/scripts/postinstall.mjs

@@ -22,7 +22,7 @@ try {
   const r = ensureMcpJson(root);
   // A refusal is a full sentence, not one of the three status words — say it on its own line
   // rather than folding it into "MCP in .mcp.json (…)", where it would read as a success.
-  if (r.startsWith("left untouched")) {
+  if (r.startsWith("left untouched") || r.startsWith("present (custom godx-ui")) {
     console.log(`\n  @godxjp/ui → .mcp.json ${r}\n`);
   }
   // The mandate is plain text the agent reads every turn (CLAUDE.md block + workflow file). It

package/scripts/ui-audit.mjs

@@ -1006,7 +1006,7 @@ function staleOwnedRules() {
       `This file is written by @godxjp/ui and says version ${stamped}, but the installed package ` +
       `is ${installed}. Its rules describe a different library than the one you are building ` +
       "against — most likely because `ignore-scripts=true` kept our postinstall from running.",
-    replacement: 'INIT_CWD="$PWD" node node_modules/@godxjp/ui/scripts/postinstall.mjs',
+    replacement: "npx @godxjp/ui sync-rules",
     snippet: `<!-- godxjp-ui:version ${stamped} --> vs installed ${installed}`,
   };
 }