@starci/skills 1.1.0

package/knowledge/ui/composition/coverage.vi.md

@@ -0,0 +1,37 @@
+# Coverage composition
+
+File này trả lời đúng một câu hỏi: receipt của direction phải liệt kê ra những gì, để một operator
+về sau chạy được đúng direction đó thay vì phải đoán.
+
+Mọi chủ đề composition khác ràng buộc từng quyết định một. Chủ đề này ràng buộc cả cái receipt. Năm
+chủ đề từng khép lại bằng một rule phạm vi của riêng mình, và năm bản sao của cùng một ý tưởng thì
+sớm muộn cũng trôi mỗi bản một hướng. Cả năm đã nghỉ, gộp vào rule bên dưới, và số của chúng không
+được dùng lại; đã nghỉ là `ACTION-4`, `STATE-4`, `FEEDBACK-4`, `LAYOUT-5` và `RESPONSIVE-5`. Phần
+liệt kê đó đáng giá tới đâu lại được quyết ở chỗ khác: bố cục và gu thẩm mỹ đến từ idiom và playbook
+trong `knowledge/grammars/starci`, còn rule này chỉ khẳng định rằng receipt đã nói đủ để bất kỳ ai
+cũng kiểm được.
+
+## COVERAGE-1 — Receipt phải liệt kê những gì
+
+Chi phối những trường mà một `frontend-direction-decision.json` đã quyết phải mang trước khi được phát ra.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Direction giao bất kỳ action nào | `coverage.actions[]` không rỗng, và mỗi mục gọi tên đường chuột, đường bàn phím, cùng mọi state có tên chạm tới được của action đó, gồm enabled, disabled, pending và đã kết thúc, nên không đường nào và không state nào bị bỏ ngầm |
+| Case 2 | Có action nhận việc mà việc không kết thúc ngay | Mọi đường pending trong `coverage.actions[]` đều gọi tên điểm kết thúc của nó, kể cả huỷ; không mục nào khai một đường pending mà thiếu điểm kết thúc |
+| Case 3 | Direction khai báo các vùng | `coverage.regions[]` không rỗng và phủ hết mọi mục trong `regionModel`, và mỗi mục gọi tên một idiom trong `knowledge/grammars/starci/playbook.md` cùng một composition công khai; không vùng nào phân giải về một cách sắp xếp trần |
+| Case 4 | Composition đổi hình dạng khi không gian đổi | `coverage.responsive[]` không rỗng và mỗi nhánh gọi tên đúng một owner, là một container query công khai hoặc một viewport query công khai; không nhánh nào gọi tên thiết bị và không nhánh nào gọi tên hai owner |
+| Case 5 | Tính năng có hơn một điều kiện | `coverage.states[]` không rỗng, mỗi mục gọi tên ý nghĩa trước rồi mới tới carrier, và không carrier nào đứng cho hai ý nghĩa |
+| Case 6 | Một family hoặc ứng dụng thêm delta lên trên một owner công khai | Từng tầng được liệt kê riêng, để một hiệu ứng bị nhân đôi, một state selected bị mất, một trigger gọn bị mất hay một thông báo bị lặp đều quy được về đúng tầng gây ra nó |
+
+Không phải rule này: việc đo đạc, chạy mẫu và đếm thông báo là công việc của operator audit; rule
+này chỉ cố định điều mà receipt đã hứa.
+
+## File này không quyết định
+
+Trang có những vùng nào và ai sở hữu track thuộc [Layout](layout.vi.md), còn nhánh nào sống sót qua
+reflow thuộc [Responsive](responsive.vi.md). Có những điều kiện nào và carrier nào giữ từng cái
+thuộc [State](state.vi.md). Một lần kích hoạt làm gì thuộc [Action](action.vi.md), và người đọc được
+nói gì ở mỗi kết cục thuộc [Feedback](feedback.vi.md). Những đường đã liệt kê có đứng vững sau khi
+render không thuộc [Focus](../proof/focus.vi.md), [Accessibility](../proof/accessibility.vi.md) và
+[Render truth](../proof/render-truth.vi.md).

package/knowledge/ui/composition/cta.md

@@ -0,0 +1,79 @@
+# Call to action composition
+
+This file answers one question: within a decision region, which action deserves the emphasis, and
+what does its emphasis promise the reader about the consequence?
+
+A call to action is settled from consequence, never from a wish for a larger or brighter control.
+The variant, the semantics, the blocked states, and the order of an action group are all decided
+before the region is built, because each of them is a promise the rendered page then has to keep.
+
+## CTA-1 — Emphasis follows consequence
+
+Governs which control carries the strongest treatment.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A decision region has one clear next action | Exactly one `Button variant="primary"` sits in that decision owner, carrying `onPress`, or `href` when the next step is a destination |
+| Case 2 | Other actions in the same region are real alternatives | Each carries a weaker published variant from `secondary`, `tertiary`, `outline`, or `ghost` that states its actual consequence |
+| Case 3 | The direction wants a bigger or brighter control without a change in consequence | The variant is unchanged, and no local button recipe appears against that control |
+| Case 4 | The action sits in a dense toolbar, a card, or a page-level decision | `size` is bound through the published prop from that interaction context, and no vendor button is restyled to reach it |
+
+Not this rule: counting how much dominant emphasis a whole page spends is ACCENT-1.
+
+## CTA-2 — Destination or command
+
+Governs which native thing the reader is actually operating.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | Activating the control takes the reader to a real address | `TextAction` or `Button` carries `href`, and the button shape changes only the paint |
+| Case 2 | Activating the control changes application state | `Button`, or `TextAction` where the command reads as text, carries a real handler |
+| Case 3 | The action carries a directional glyph | The glyph sits in `startContent` or `endContent`, and the visible text label remains |
+| Case 4 | The direction wants an icon-only arrow as the continuation | The dominant decision keeps a visible text label, and every glyph on it is supporting |
+
+Not this rule: how many effects one activation may produce is ACTION-1.
+
+## CTA-3 — Unavailable, pending, and unresolved are three conditions
+
+Governs which of three temporary blocks the control is actually in.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | The work cannot start at all, because permission or prerequisites are missing | `isDisabled` is bound on that control, and no pending carrier is |
+| Case 2 | This control accepted work that has not settled | `isPending` is bound on that same control, its visible label and outer box are unchanged, and duplicate activation is refused |
+| Case 3 | Initial content has not resolved and no action has been taken | `isSkeleton` is bound on the owner, and no pending carrier appears anywhere for that content |
+| Case 4 | Some other request is in flight elsewhere on the page | Peer controls keep their own carriers, and no pending reaches a control that started nothing |
+
+Not this rule: which owner holds pending once several controls are involved is ACTION-2.
+
+## CTA-4 — Destructive consequence needs its own authority
+
+Governs the final action that cannot be undone.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | An action irreversibly deletes, revokes, or discards valuable state | The receipt carries explicit destructive copy, a confirmation proportionate to the consequence, and a typed danger action treatment |
+| Case 2 | The published `ButtonVariant` offers no danger value | A `GRAMMAR_REQUIRED` gap records it, and the CTA does not ship on the primary variant instead |
+| Case 3 | The direction is tempted to import the vendor danger variant, or to add local red | No vendor danger variant and no local red appears against that control |
+| Case 4 | The action is a reversible cancel or an ordinary negative outcome | It carries no destructive treatment and no confirmation earned by destructiveness |
+
+## CTA-5 — Group order across widths
+
+Governs the sequence of two or more actions that form one decision.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A decision offers a dominant action, an alternative, and a way out | DOM order runs dominant decision, supporting alternative, then escape or recovery, as the product requires |
+| Case 2 | The group wraps or stacks at a narrower width | Reading order and sequential focus order are identical at every width, and no CSS `order` reverses the group |
+| Case 3 | A translated label grows well past its original length | The receipt names the longest label the group must hold, and the group wraps or stacks rather than overlapping at that length |
+| Case 4 | Two actions live in separate regions | They belong to separate decision owners in the receipt, and neither ranks against the other |
+
+## What this file does not decide
+
+Which region holds the decision is [Layout](layout.md), and which anchor names it is
+[Hierarchy](hierarchy.md). How many effects an activation may produce and who owns pending is
+[Action](action.md). How scarce the dominant treatment is across the page is [Accent](accent.md),
+and what happens after the action settles is [Feedback](feedback.md). What the receipt must
+enumerate about these actions is [Coverage](coverage.md). Whether the rendered control is reachable,
+named, and visibly focused is [Accessibility](../proof/accessibility.md) and
+[Focus](../proof/focus.md).

package/knowledge/ui/composition/cta.vi.md

@@ -0,0 +1,79 @@
+# Call to action composition
+
+File này trả lời đúng một câu hỏi: trong một vùng quyết định, action nào xứng đáng được nhấn mạnh,
+và điểm nhấn đó hứa với người đọc điều gì về hệ quả.
+
+Call to action được chốt từ hệ quả, không bao giờ từ mong muốn có một control to hơn hay sáng hơn.
+Variant, ngữ nghĩa, các trạng thái bị chặn và thứ tự của một nhóm action đều được quyết trước khi
+dựng vùng, bởi mỗi thứ trong số đó là một lời hứa mà trang sau khi render phải giữ.
+
+## CTA-1 — Điểm nhấn đi theo hệ quả
+
+Chi phối control nào mang treatment mạnh nhất.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một vùng quyết định có đúng một bước kế tiếp rõ ràng | Đúng một `Button variant="primary"` nằm trong decision owner đó, mang `onPress`, hoặc mang `href` khi bước kế tiếp là một điểm đến |
+| Case 2 | Các action khác trong cùng vùng là lựa chọn thay thế thật sự | Mỗi cái mang một variant công khai yếu hơn trong `secondary`, `tertiary`, `outline` hoặc `ghost`, nói đúng hệ quả thật của nó |
+| Case 3 | Direction muốn control to hơn hoặc chói hơn mà hệ quả không đổi | Variant không đổi, và không công thức button cục bộ nào đứng cạnh control đó |
+| Case 4 | Action nằm trong toolbar dày, trong card, hay ở tầm quyết định của cả trang | `size` được gắn qua prop công khai theo đúng bối cảnh tương tác đó, và không button vendor nào bị sơn lại để đạt được nó |
+
+Không phải rule này: đếm xem cả trang tiêu bao nhiêu điểm nhấn chủ đạo thuộc ACCENT-1.
+
+## CTA-2 — Điểm đến hay câu lệnh
+
+Chi phối việc người đọc thật ra đang thao tác với thứ native nào.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Kích hoạt sẽ đưa người đọc tới một địa chỉ thật | `TextAction` hoặc `Button` mang `href`, và hình dạng nút chỉ đổi phần sơn |
+| Case 2 | Kích hoạt sẽ thay đổi state của ứng dụng | `Button`, hoặc `TextAction` khi câu lệnh cần đọc như chữ, mang một handler thật |
+| Case 3 | Action mang một glyph chỉ hướng | Glyph nằm trong `startContent` hoặc `endContent`, và nhãn chữ nhìn thấy được vẫn ở lại |
+| Case 4 | Direction muốn một mũi tên không kèm chữ làm bước tiếp | Quyết định chủ đạo giữ nhãn chữ nhìn thấy được, và mọi glyph trên nó chỉ là phần bổ trợ |
+
+Không phải rule này: một lần kích hoạt được phép sinh ra bao nhiêu hiệu ứng thuộc ACTION-1.
+
+## CTA-3 — Không dùng được, đang chạy và chưa giải quyết là ba điều kiện
+
+Chi phối việc control đang thật sự nằm ở dạng chặn nào trong ba dạng.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Việc không thể bắt đầu, vì thiếu quyền hoặc thiếu tiền đề | `isDisabled` được gắn trên control đó, và không carrier pending nào được gắn |
+| Case 2 | Chính control này đã nhận việc và việc chưa xong | `isPending` được gắn trên đúng control đó, nhãn nhìn thấy được và khung ngoài không đổi, và kích hoạt lần hai bị từ chối |
+| Case 3 | Nội dung ban đầu chưa giải quyết và chưa ai bấm gì | `isSkeleton` được gắn trên owner, và không carrier pending nào xuất hiện ở đâu cho nội dung đó |
+| Case 4 | Có một request khác đang chạy ở chỗ khác trên trang | Các control ngang hàng giữ carrier của riêng chúng, và không pending nào chạm tới một control chưa khởi động gì |
+
+Không phải rule này: khi nhiều control cùng tham gia thì ai giữ pending thuộc ACTION-2.
+
+## CTA-4 — Hệ quả huỷ hoại cần authority riêng
+
+Chi phối action cuối cùng mà không thể hoàn tác.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một action xoá, thu hồi hoặc vứt bỏ vĩnh viễn thứ có giá trị | Receipt mang copy nêu rõ tính huỷ hoại, một bước xác nhận tương xứng với hệ quả, và một treatment action danger có kiểu |
+| Case 2 | `ButtonVariant` công khai chưa có giá trị danger | Một gap `GRAMMAR_REQUIRED` ghi nhận điều đó, và CTA không được đưa lên variant primary để thay thế |
+| Case 3 | Direction bị cám dỗ import variant danger của vendor, hoặc thêm màu đỏ cục bộ | Không variant danger của vendor và không màu đỏ cục bộ nào đứng cạnh control đó |
+| Case 4 | Action là một thao tác huỷ có thể hoàn tác hoặc một kết cục tiêu cực thường | Nó không mang treatment huỷ hoại và không mang bước xác nhận sinh ra từ tính huỷ hoại |
+
+## CTA-5 — Thứ tự nhóm qua các bề rộng
+
+Chi phối trình tự của hai action trở lên cùng tạo nên một quyết định.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một quyết định có action chủ đạo, một lựa chọn thay thế và một lối ra | Thứ tự DOM chạy từ quyết định chủ đạo, tới lựa chọn thay thế, rồi tới lối ra hoặc lối phục hồi, tuỳ sản phẩm yêu cầu |
+| Case 2 | Nhóm wrap hoặc xếp chồng ở bề rộng hẹp hơn | Thứ tự đọc và thứ tự focus tuần tự trùng khít nhau ở mọi bề rộng, và không CSS `order` nào đảo nhóm |
+| Case 3 | Một nhãn đã dịch dài hơn hẳn bản gốc | Receipt gọi tên nhãn dài nhất mà nhóm phải chứa, và ở độ dài đó nhóm wrap hoặc xếp chồng chứ không chồng lấn |
+| Case 4 | Hai action nằm ở hai vùng khác nhau | Chúng thuộc hai decision owner riêng trong receipt, và không cái nào so cấp với cái kia |
+
+## File này không quyết định
+
+Vùng nào chứa quyết định thuộc [Layout](layout.vi.md), và anchor nào gọi tên vùng thuộc
+[Hierarchy](hierarchy.vi.md). Một lần kích hoạt được sinh bao nhiêu hiệu ứng và ai giữ pending thuộc
+[Action](action.vi.md). Treatment chủ đạo khan hiếm tới đâu trên cả trang thuộc
+[Accent](accent.vi.md), và sau khi action xong thì nói gì thuộc [Feedback](feedback.vi.md). Receipt
+phải liệt kê những gì về các action này thuộc [Coverage](coverage.vi.md). Control sau khi render có
+chạm tới được, có tên và có focus nhìn thấy được không thuộc
+[Accessibility](../proof/accessibility.vi.md) và [Focus](../proof/focus.vi.md).

package/knowledge/ui/composition/feedback.md

@@ -0,0 +1,55 @@
+# Feedback composition
+
+This file answers one question: when something fails, succeeds, or needs correcting, who says so,
+and how small is that owner?
+
+Feedback is decided at the smallest place that can actually be corrected or recovered. A failure
+announced further out than it can be fixed makes the reader hunt for the cause, and a page-level
+recovery for a single failed panel throws away work that never failed.
+
+## FEEDBACK-1 — Correct at the nearest owner
+
+Governs where a validation failure lives.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | One field has a current validation failure the reader can fix at that field | `Input.errorMessage` on that field carries the failure and the correction, and `isError` is bound to the same invalid fact |
+| Case 2 | The field has standing guidance that is true whether or not it failed | That guidance sits in `hint`, and it does not appear or disappear with validation |
+| Case 3 | The same failure would also be summarised above the form | Exactly one owner states that failure, and it is the field |
+| Case 4 | The message is navigation or general status rather than a rejected value | No validation carrier holds it; it resolves to a status owner elsewhere |
+| Case 5 | The value changes, or validation runs again | The error updates or clears with the fact, and the reader's entry survives unchanged |
+
+## FEEDBACK-2 — Recover at the smallest actionable owner
+
+Governs where a retry lives.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | One region is empty or failed and has a real next step | `EmptyNotice` names the affected region and carries `actionLabel` and `onAction` for that step, with `description` optional |
+| Case 2 | The recovery action has accepted work | `isActionPending` is bound while that action runs, and to no other action |
+| Case 3 | A page-level reload would be simpler to wire | The recovery is scoped to the operation that failed; no page-level reload stands in for one failed region |
+| Case 4 | Repeating the operation is not safe, as with a purchase | The recovery is a distinct safe operation backed by authority, not a repeat of the unsafe one |
+| Case 5 | The reader has unsaved work elsewhere on the page | Only the failed region is replaced, and work outside it survives the recovery |
+
+## FEEDBACK-3 — Settlement must be known before it is claimed
+
+Governs the moment a result may be stated.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A command is waiting on a result | Pending clears only on a real settlement, and the result copy names the outcome that actually arrived |
+| Case 2 | A non-urgent result should be announced | `Text live="polite"` sits on the smallest owner of that status |
+| Case 3 | The message is genuinely urgent and interrupting is warranted | `live="assertive"` is bound only there, and to nothing else in the tree |
+| Case 4 | The same result would appear in two places | Exactly one announcement owner holds that result, and it updates only when the result changes |
+| Case 5 | The message describes navigation | It is produced by an actual navigation effect, and it carries no error semantics unless the navigation itself failed |
+| Case 6 | The result matters after the moment passes | A durable owner holds it after the announcement, where the reader can review or act on it |
+
+Retired: FEEDBACK-4 is retired into COVERAGE-1 and is not reused; the address stays spent.
+
+## What this file does not decide
+
+Who owns pending among several controls is [Action](action.md), and which conditions exist at all is
+[State](state.md). Which action the reader is being pushed towards is [CTA](cta.md). What the
+receipt must enumerate about these outcome paths is [Coverage](coverage.md). Whether a message is
+programmatically related to its field, and whether it is announced once, is
+[Accessibility](../proof/accessibility.md) and [Render truth](../proof/render-truth.md).

package/knowledge/ui/composition/feedback.vi.md

@@ -0,0 +1,56 @@
+# Feedback composition
+
+File này trả lời đúng một câu hỏi: khi có thứ gì đó hỏng, thành công, hoặc cần sửa, ai là người
+thông báo, và owner đó nhỏ tới đâu.
+
+Feedback được chốt ở chỗ nhỏ nhất mà thật sự sửa hoặc phục hồi được. Một lỗi báo ở nơi xa hơn chỗ có
+thể sửa nó sẽ bắt người đọc đi tìm nguyên nhân, còn một lối phục hồi ở tầm cả trang cho một panel
+hỏng sẽ ném đi cả phần công việc chưa từng hỏng.
+
+## FEEDBACK-1 — Sửa ở owner gần nhất
+
+Chi phối chỗ ở của một lỗi validation.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một field đang có lỗi validation mà người đọc sửa được ngay tại field đó | `Input.errorMessage` trên chính field đó mang cả lỗi lẫn cách sửa, và `isError` gắn vào đúng dữ kiện không hợp lệ ấy |
+| Case 2 | Field có phần hướng dẫn thường trực, đúng dù nó có lỗi hay không | Phần hướng dẫn đó nằm trong `hint`, và nó không xuất hiện rồi biến mất theo validation |
+| Case 3 | Cùng lỗi đó còn được tóm tắt lại ở phía trên form | Đúng một owner nêu lỗi đó, và owner ấy là field |
+| Case 4 | Thông điệp là điều hướng hoặc trạng thái chung chứ không phải một giá trị bị từ chối | Không carrier validation nào giữ nó; nó phân giải về một owner status ở chỗ khác |
+| Case 5 | Giá trị thay đổi, hoặc validation chạy lại | Lỗi được cập nhật hoặc gỡ đi theo dữ kiện, và phần người đọc đã nhập còn nguyên |
+
+## FEEDBACK-2 — Phục hồi ở owner hành động nhỏ nhất
+
+Chi phối chỗ ở của một nút thử lại.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một vùng rỗng hoặc vùng lỗi có một bước kế tiếp thật | `EmptyNotice` gọi tên đúng vùng bị ảnh hưởng và mang `actionLabel` cùng `onAction` cho bước đó, `description` là tuỳ chọn |
+| Case 2 | Action phục hồi đã nhận việc | `isActionPending` được gắn trong lúc action đó chạy, và không gắn cho action nào khác |
+| Case 3 | Nối một nút tải lại cả trang thì dễ hơn | Lối phục hồi được giới hạn đúng vào thao tác đã hỏng; không nút tải lại cả trang nào đứng thay cho một vùng hỏng |
+| Case 4 | Lặp lại thao tác là không an toàn, như với một giao dịch mua | Lối phục hồi là một thao tác an toàn riêng biệt có authority chống lưng, không phải lần lặp lại thao tác không an toàn |
+| Case 5 | Người đọc còn công việc chưa lưu ở chỗ khác trên trang | Chỉ vùng đã hỏng bị thay, và phần việc ngoài nó sống sót qua lần phục hồi |
+
+## FEEDBACK-3 — Phải biết việc đã kết thúc rồi mới được nói
+
+Chi phối thời điểm được phép nêu một kết quả.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một câu lệnh đang chờ kết quả | Pending chỉ gỡ khi có một kết thúc thật, và copy kết quả gọi tên đúng kết cục đã về |
+| Case 2 | Một kết quả không khẩn cần được đọc lên | `Text live="polite"` nằm trên owner nhỏ nhất của status đó |
+| Case 3 | Thông điệp thật sự khẩn và việc cắt ngang là chính đáng | `live="assertive"` chỉ được gắn ở đó, và không gắn ở đâu khác trong cây |
+| Case 4 | Cùng một kết quả sẽ xuất hiện ở hai chỗ | Đúng một owner thông báo giữ kết quả đó, và nó chỉ cập nhật khi kết quả đổi |
+| Case 5 | Thông điệp mô tả việc điều hướng | Nó sinh ra từ một hiệu ứng điều hướng thật, và nó không mang ngữ nghĩa lỗi trừ khi chính việc điều hướng đã hỏng |
+| Case 6 | Kết quả còn quan trọng sau khi khoảnh khắc đó trôi qua | Một owner bền giữ nó sau lần thông báo, nơi người đọc xem lại hoặc hành động tiếp được |
+
+Retired: FEEDBACK-4 đã nghỉ, gộp vào COVERAGE-1, và số này không được dùng lại; địa chỉ đó coi như đã tiêu.
+
+## File này không quyết định
+
+Khi nhiều control cùng tham gia thì ai giữ pending thuộc [Action](action.vi.md), và có những điều
+kiện nào thuộc [State](state.vi.md). Người đọc đang được đẩy về phía action nào thuộc
+[CTA](cta.vi.md). Receipt phải liệt kê những gì về các đường kết cục này thuộc
+[Coverage](coverage.vi.md). Một thông điệp có được gắn về đúng field của nó không, và có được đọc
+lên đúng một lần không, thuộc [Accessibility](../proof/accessibility.vi.md) và
+[Render truth](../proof/render-truth.vi.md).

package/knowledge/ui/composition/hierarchy.md

@@ -0,0 +1,83 @@
+# Hierarchy composition
+
+This file answers one question: given a piece of business meaning, which information rank does it
+receive, and where does it sit relative to everything else in its region?
+
+Hierarchy is decided from the job the content does, never from how prominent the direction wishes it
+looked. Rank is carried by a published semantic owner, so the outline a screen reader walks and the
+outline a reader sees are the same outline.
+
+## HIERARCHY-1 — Rank comes from the job, not the look
+
+Governs which semantic owner carries a piece of content.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | Content names a page or a section | `Heading` carries it, at the level the outline requires |
+| Case 2 | Content explains, or states a neutral fact | `Text` in its default role carries it, with no state owner attached |
+| Case 3 | Content reports a compact outcome backed by authority | `Badge`, or another published state owner for that outcome, carries it |
+| Case 4 | Content reports a verified numeric completion | `Progress` carries it, with a label and value that describe the same verified measurement |
+| Case 5 | Something feels important but matches no published role | The receipt names the job before any owner is bound, and no local type utility stands in for a rank |
+
+Not this rule: how much emphasis paint that rank receives is ACCENT-1.
+
+## HIERARCHY-2 — One strongest anchor per region
+
+Governs how many things may name the same region.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A region carries a name plus supporting copy, facts, statuses, or actions | Exactly one strongest semantic anchor names the region's job, through `SectionHeader`, `Heading`, or a labelled surface |
+| Case 2 | Two candidates both look like the region's name | Either the receipt lists two peer regions each with its own anchor, or one candidate carries a weaker rank |
+| Case 3 | A status wants to be louder than the thing it describes | The status ranks below the name it qualifies |
+| Case 4 | Independent peer regions sit side by side | Each region's anchor is settled within that region; no anchor ranks against another region's anchor |
+
+Not this rule: which region comes first on the page is LAYOUT-1.
+
+## HIERARCHY-3 — Reading order equals task dependency
+
+Governs the sequence in which meaning is delivered.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | The reader needs context before making a choice | DOM order runs prerequisite, decision, consequence, then support |
+| Case 2 | A layout would read better with the pieces rearranged at one width | The composition differs at that width and the meaning order does not; no CSS `order` reverses meaning |
+| Case 3 | Help text explains a field or a task | It follows the thing it explains in DOM order and in the accessibility tree |
+| Case 4 | A result is produced by an action on the same surface | The action precedes the result it produces, at every width |
+
+Not this rule: whether sequential keyboard focus actually follows this order once rendered is
+FOCUS-2.
+
+## HIERARCHY-4 — Facts, measurement, and outcome are separate ranks
+
+Governs the boundary between what is merely true, what is measured, and what has been decided.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | The content is a neutral fact with no claim attached | `Text` carries it, with no status and no success treatment |
+| Case 2 | The content is a measurement between 0 and 100 backed by authority | `Progress` carries it, and its label and value describe the same verified measurement |
+| Case 3 | The measurement has not resolved yet | `Progress isSkeleton` carries it, and no zero value is rendered in its place |
+| Case 4 | The content is an outcome someone can act on | An explicit outcome word plus its state owner carries it; no colour alone states the outcome |
+| Case 5 | The direction is tempted to let one rank imply another | No filled bar stands for a completion, and no ordinary fact takes a warning treatment |
+
+## HIERARCHY-5 — Rank survives reflow, loading, and lost colour
+
+Governs the conditions under which the chosen hierarchy must still hold.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | The region stacks at a narrow width | Heading order and the count of strongest anchors are identical to the wide branch; only placement differs |
+| Case 2 | Content is still loading | The skeleton carries the same selected role as the resolved content, so no rank changes when real content arrives |
+| Case 3 | Optional content is missing in some states | Every rank present in one state has a carrier that survives the states where the optional content is absent |
+| Case 4 | Colour is removed, or the viewer is in forced colours | Every rank distinction still resolves to a semantic or structural cue |
+
+Not this rule: capturing the zoomed, forced-colour, and colour-removed renders is the audit
+operator's work.
+
+## What this file does not decide
+
+Which regions exist and who owns their tracks is [Layout](layout.md). How rank behaves as space
+changes is [Responsive](responsive.md). Which action is dominant is [CTA](cta.md), and how scarce
+emphasis is spent is [Accent](accent.md). The rendered accessibility tree that proves this outline
+is [Accessibility](../proof/accessibility.md), and agreement between rank and product truth is
+[Render truth](../proof/render-truth.md).

package/knowledge/ui/composition/hierarchy.vi.md

@@ -0,0 +1,82 @@
+# Hierarchy composition
+
+File này trả lời đúng một câu hỏi: một mảng ý nghĩa business thì nhận cấp độ thông tin nào, và nó
+đứng ở đâu so với mọi thứ còn lại trong vùng của nó.
+
+Cấp độ được quyết từ công việc mà nội dung đang làm, không bao giờ từ mong muốn cho nó trông nổi bật
+hơn. Cấp độ do một semantic owner công khai mang, nhờ vậy dàn bài mà trình đọc màn hình đi qua và
+dàn bài mà mắt người đọc thấy vẫn là cùng một dàn bài.
+
+## HIERARCHY-1 — Cấp độ đến từ công việc, không đến từ vẻ ngoài
+
+Chi phối việc semantic owner nào mang một mảng nội dung.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Nội dung đặt tên cho một trang hoặc một section | `Heading` mang nó, ở đúng level mà dàn bài yêu cầu |
+| Case 2 | Nội dung giải thích, hoặc nêu một sự kiện trung tính | `Text` ở vai trò mặc định mang nó, không gắn kèm state owner nào |
+| Case 3 | Nội dung báo một kết cục ngắn gọn có authority chống lưng | `Badge`, hoặc một state owner công khai khác cho kết cục đó, mang nó |
+| Case 4 | Nội dung báo một mức hoàn thành đã được kiểm chứng | `Progress` mang nó, với label và value cùng mô tả một phép đo đã kiểm chứng |
+| Case 5 | Có thứ trông quan trọng nhưng không khớp vai trò công khai nào | Receipt gọi tên công việc của nó trước khi gắn owner, và không utility type cục bộ nào đứng thay cho một cấp độ |
+
+Không phải rule này: cấp độ đó nhận bao nhiêu điểm nhấn thuộc ACCENT-1.
+
+## HIERARCHY-2 — Mỗi vùng một anchor mạnh nhất
+
+Chi phối số thứ được phép đặt tên cho cùng một vùng.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một vùng có tên gọi cộng với phần bổ trợ, dữ kiện, trạng thái hoặc action | Đúng một anchor ngữ nghĩa mạnh nhất gọi tên công việc của vùng, qua `SectionHeader`, `Heading` hoặc một surface có nhãn |
+| Case 2 | Hai ứng viên cùng trông như tên của vùng | Hoặc receipt liệt kê hai vùng ngang hàng, mỗi vùng một anchor, hoặc một ứng viên mang cấp độ yếu hơn |
+| Case 3 | Một trạng thái muốn to tiếng hơn thứ mà nó mô tả | Trạng thái xếp dưới cái tên mà nó bổ nghĩa |
+| Case 4 | Các vùng ngang hàng độc lập nằm cạnh nhau | Anchor của mỗi vùng được chốt trong chính vùng đó; không anchor nào so cấp với anchor của vùng khác |
+
+Không phải rule này: vùng nào đứng trước trên trang thuộc LAYOUT-1.
+
+## HIERARCHY-3 — Thứ tự đọc bằng đúng thứ tự phụ thuộc của nhiệm vụ
+
+Chi phối trình tự mà ý nghĩa được trao cho người đọc.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Người đọc cần bối cảnh trước khi ra lựa chọn | Thứ tự DOM chạy tiền đề, quyết định, hệ quả, rồi phần bổ trợ |
+| Case 2 | Ở một bề rộng nào đó bố cục sẽ đọc mượt hơn nếu đảo các mảnh | Composition khác đi ở bề rộng đó còn thứ tự ý nghĩa thì không; không CSS `order` nào đảo ngược ý nghĩa |
+| Case 3 | Có phần trợ giúp giải thích một field hoặc một nhiệm vụ | Nó đứng sau thứ mà nó giải thích, trong thứ tự DOM và trong accessibility tree |
+| Case 4 | Một kết quả do một action trên cùng surface sinh ra | Action đứng trước kết quả mà nó sinh ra, ở mọi bề rộng |
+
+Không phải rule này: chuyện focus tuần tự có thật sự đi theo thứ tự này sau khi render thuộc FOCUS-2.
+
+## HIERARCHY-4 — Dữ kiện, phép đo và kết cục là ba cấp độ khác nhau
+
+Chi phối ranh giới giữa cái chỉ đơn thuần là đúng, cái đã được đo, và cái đã được kết luận.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Nội dung là một dữ kiện trung tính, không kèm tuyên bố nào | `Text` mang nó, không kèm trạng thái và không kèm treatment thành công |
+| Case 2 | Nội dung là một phép đo từ 0 đến 100 có authority chống lưng | `Progress` mang nó, và label cùng value mô tả đúng một phép đo đã kiểm chứng |
+| Case 3 | Phép đo chưa giải quyết xong | `Progress isSkeleton` mang nó, và không giá trị không nào được render thay chỗ |
+| Case 4 | Nội dung là một kết cục mà người đọc có thể hành động theo | Một từ nêu kết cục rõ ràng cùng state owner của nó mang việc đó; không màu nào tự mình nêu kết cục |
+| Case 5 | Direction bị cám dỗ để một cấp độ ngụ ý một cấp độ khác | Không thanh đầy nào đứng cho một mức hoàn thành, và không dữ kiện bình thường nào nhận treatment cảnh báo |
+
+## HIERARCHY-5 — Cấp độ sống sót qua reflow, qua lúc tải và qua khi mất màu
+
+Chi phối những điều kiện mà phân cấp đã chọn vẫn phải đứng vững.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Vùng xếp chồng lại ở bề rộng hẹp | Thứ tự heading và số anchor mạnh nhất trùng khít nhánh rộng; chỉ vị trí là khác |
+| Case 2 | Nội dung còn đang tải | Skeleton mang đúng vai trò đã chọn của nội dung thật, nên không cấp độ nào nhảy khi nội dung thật về |
+| Case 3 | Nội dung tuỳ chọn vắng mặt ở một số trạng thái | Mọi cấp độ có mặt ở một trạng thái đều có carrier sống sót qua các trạng thái mà nội dung tuỳ chọn vắng mặt |
+| Case 4 | Màu bị bỏ đi, hoặc người xem đang ở chế độ forced colors | Mọi khác biệt cấp độ vẫn phân giải về một dấu hiệu ngữ nghĩa hoặc cấu trúc |
+
+Không phải rule này: việc chụp lại các bản render đã zoom, forced colors và đã bỏ màu là công việc
+của operator audit.
+
+## File này không quyết định
+
+Trang có những vùng nào và ai sở hữu track thuộc [Layout](layout.vi.md). Cấp độ hành xử ra sao khi
+không gian đổi thuộc [Responsive](responsive.vi.md). Action nào là chủ đạo thuộc [CTA](cta.vi.md),
+và phần nhấn mạnh khan hiếm tiêu ở đâu thuộc [Accent](accent.vi.md). Cây accessibility chứng minh
+dàn bài này nằm ở [Accessibility](../proof/accessibility.vi.md), còn sự khớp nhau giữa cấp độ và sự
+thật sản phẩm nằm ở [Render truth](../proof/render-truth.vi.md).

package/knowledge/ui/composition/layout.md

@@ -0,0 +1,91 @@
+# Layout composition
+
+This file answers one question: before any DOM exists, which visible task regions does this page
+have, and who owns each one?
+
+Layout is the first composition decision. It settles how many regions the reader sees, which
+published composition owns each region's tracks and scrolling, and what happens to a region that
+leaves normal flow or disappears. Everything measured after the page renders belongs to the audit
+operator, not to this file.
+
+## Owner vocabulary
+
+| Owner | Meaning |
+| --- | --- |
+| A composition name | `@starci/grammar/common` already owns that region's tracks and geometry |
+| `App` | The direction supplies content, state, and labels into a published slot |
+| `—` | No published composition covers this region; the direction records the gap |
+
+Reaching for a vendor grid where a composition name is the owner is `APP_REIMPLEMENTATION`.
+Reaching for one where the owner is `—` is `COMMON_CAPABILITY_MISSING`, and the answer is to add the
+reusable composition, not to author an application grid.
+
+## LAYOUT-1 — Which regions exist at all
+
+Governs how many visible task regions the page carries and what justifies each one.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | Business content has one task and no supporting material | The receipt lists exactly one dominant region, and every further region it lists carries a named task role |
+| Case 2 | A primary task has support the reader consults alongside it | The support is a rail, and the receipt names the task role that earns it |
+| Case 3 | Routed page content needs shell chrome around it | `WorkspaceShell` owns the shell regions, and exactly one element is named as the main landmark |
+| Case 4 | Destinations need to be grouped and browsed | `Sidebar` owns the grouping; the receipt supplies only destinations and labels into it |
+| Case 5 | A conversation needs a composer that stays put | `ChatWorkspace` owns the pairing of conversation and composer |
+| Case 6 | The required arrangement has no published composition | A `GRAMMAR_REQUIRED` gap names the missing composition, and no substitute arrangement appears in the tree |
+
+Not this rule: which of several regions carries the strongest anchor is HIERARCHY-2.
+
+## LAYOUT-2 — Every region's owner is a published composition
+
+Governs which code decides a region's tracks, not which content sits inside them.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A primary column sits beside a support column | `PrimaryRailLayout` owns both tracks; the receipt names only `railWidth` and `align`, and no track formula appears against that region |
+| Case 2 | Shell regions and the main landmark must be named | `WorkspaceShell` owns the slots, and the receipt supplies `primaryLabel` |
+| Case 3 | A conversation surface needs a bounded height | `ChatWorkspace` owns the bound, and the host supplies the height it requires |
+| Case 4 | The direction is tempted by a vendor grid or child width arithmetic | Every region resolves to a published composition or to a recorded gap; no vendor grid and no width arithmetic owns a region |
+| Case 5 | A family wants a region to look different | The family delta replaces a renderer with compatible props only; the region's role and its number of owners are unchanged |
+
+Not this rule: how much space separates the objects inside a region is a presentation decision.
+
+## LAYOUT-3 — One owner per region and per scroll axis
+
+Governs how many things may claim the same region or the same overflow axis.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | Several regions coexist on one page | Each visible region resolves to exactly one composition owner and one intended track |
+| Case 2 | Content is essentially wider than its column, such as a table | Exactly one named `HorizontalScrollRegion` owns the inline axis, and no page-level inline scroll exists |
+| Case 3 | Block flow must be bounded inside a region | `VerticalScrollRegion isScrollable`, or the exact named composition, owns that block axis |
+| Case 4 | A conversation must scroll while its composer stays put | `ChatWorkspace` owns conversation scrolling, and the composer is its sibling outside that scroller |
+| Case 5 | A nested scroller is proposed | Each nested scroller carries a different named axis or a different named task from its ancestor |
+
+Not this rule: whether a scroll region can actually be reached and traversed by keyboard once
+rendered is FOCUS-2.
+
+## LAYOUT-4 — Regions that leave normal flow
+
+Governs sticky, fixed, drawer, floating, reordered, and conditionally absent regions.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A support column should stay in view while the primary column scrolls | `Rail mode="sticky"` carries its published bound, and below the narrow width the region returns to normal flow |
+| Case 2 | An overlay needs bounded fixed geometry | `WorkspaceShell.floatingLayer` supplies geometry only; if focus containment and dismissal are also required, the receipt names a modal owner or records a gap |
+| Case 3 | Compact space cannot hold the conversation rail inline | `ChatWorkspace` owns the drawer, and the receipt supplies `isRailOpen` and `onRailOpenChange` |
+| Case 4 | A region is absent in the current state | No wrapper, track, divider, rule, spacer, or reserved scroll range for that region survives its absence |
+| Case 5 | The direction wants a different visual order at one width | DOM, reading, focus, and action order are identical to task order at every width; the composition differs, the order does not |
+
+Not this rule: whether the projection actually clears the content beneath it at a given viewport is
+observed by the audit operator, not settled here.
+
+Retired: LAYOUT-5 is retired into COVERAGE-1 and is not reused; the address stays spent.
+
+## What this file does not decide
+
+Which rank the content inside a region carries is [Hierarchy](hierarchy.md). How a region recomposes
+as space changes is [Responsive](responsive.md). Which action inside a region is dominant is
+[CTA](cta.md) and [Accent](accent.md). What the receipt must enumerate about these regions is
+[Coverage](coverage.md). Whether the rendered result matches this direction is the audit operator's
+business, in [Focus](../proof/focus.md), [Accessibility](../proof/accessibility.md),
+[Motion](../proof/motion.md), and [Render truth](../proof/render-truth.md).