@starci/skills 1.1.0

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

@@ -0,0 +1,93 @@
+# Layout composition
+
+File này trả lời đúng một câu hỏi: trước khi có bất kỳ cây DOM nào, trang này có những vùng nhiệm vụ
+nào mà người đọc nhìn thấy, và ai sở hữu từng vùng đó.
+
+Layout là quyết định composition đầu tiên. Nó chốt xem người đọc thấy bao nhiêu vùng, composition
+công khai nào sở hữu track và scroll của từng vùng, và chuyện gì xảy ra với một vùng khi nó rời khỏi
+dòng chảy bình thường hoặc biến mất hẳn. Mọi thứ đo được sau khi trang render đều thuộc về operator
+audit, không thuộc file này.
+
+## Từ vựng owner
+
+| Owner | Nghĩa |
+| --- | --- |
+| Tên một composition | `@starci/grammar/common` đã sở hữu track và geometry của vùng đó |
+| `App` | Direction cấp nội dung, state và label vào một slot công khai |
+| `—` | Chưa có composition công khai nào phủ được vùng này; direction ghi nhận gap |
+
+Với ra một grid của vendor ở chỗ owner là tên một composition chính là `APP_REIMPLEMENTATION`. Với ra
+một grid ở chỗ owner là `—` thì đó là `COMMON_CAPABILITY_MISSING`, và câu trả lời là bổ sung
+composition dùng lại được, chứ không phải tự dựng grid trong ứng dụng.
+
+## LAYOUT-1 — Trang có những vùng nào
+
+Chi phối số vùng nhiệm vụ mà người đọc nhìn thấy và lý do tồn tại của từng vùng.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Nội dung business chỉ có một nhiệm vụ và không có phần bổ trợ | Receipt liệt kê đúng một vùng chủ đạo, và mọi vùng khác nó liệt kê đều mang một vai trò nhiệm vụ có tên |
+| Case 2 | Nhiệm vụ chính có phần bổ trợ mà người đọc tra cứu song song | Phần bổ trợ là một rail, và receipt gọi tên vai trò nhiệm vụ đã xứng đáng có nó |
+| Case 3 | Nội dung trang được route cần khung chrome bao quanh | `WorkspaceShell` sở hữu các vùng shell, và đúng một phần tử được gọi tên là landmark chính |
+| Case 4 | Các điểm đến cần được gom nhóm để duyệt | `Sidebar` sở hữu việc gom nhóm; receipt chỉ cấp điểm đến và nhãn vào đó |
+| Case 5 | Một cuộc hội thoại cần composer luôn nằm yên tại chỗ | `ChatWorkspace` sở hữu cặp hội thoại và composer |
+| Case 6 | Cách sắp xếp cần dùng chưa có composition công khai nào | Một gap `GRAMMAR_REQUIRED` gọi tên composition còn thiếu, và không có cách sắp xếp thay thế nào xuất hiện trong cây |
+
+Không phải rule này: vùng nào trong số các vùng mang anchor mạnh nhất thuộc HIERARCHY-2.
+
+## LAYOUT-2 — Owner của mọi vùng là một composition công khai
+
+Chi phối phần code nào quyết định track của một vùng, chứ không phải nội dung nào nằm trong đó.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một cột chính nằm cạnh một cột bổ trợ | `PrimaryRailLayout` sở hữu cả hai track; receipt chỉ gọi tên `railWidth` và `align`, và không công thức track nào đứng cạnh vùng đó |
+| Case 2 | Các vùng shell và landmark chính cần được gọi tên | `WorkspaceShell` sở hữu các slot, và receipt cấp `primaryLabel` |
+| Case 3 | Một surface hội thoại cần chiều cao có biên | `ChatWorkspace` sở hữu biên đó, và host cấp chiều cao mà nó yêu cầu |
+| Case 4 | Direction bị cám dỗ dùng grid của vendor hoặc tự tính bề rộng con | Mọi vùng phân giải về một composition công khai hoặc về một gap đã ghi nhận; không grid vendor và không phép tính bề rộng nào sở hữu một vùng |
+| Case 5 | Một family muốn một vùng trông khác đi | Delta của family chỉ thay renderer bằng props tương thích; vai trò của vùng và số lượng owner của nó không đổi |
+
+Không phải rule này: khoảng cách giữa các object bên trong một vùng là quyết định của presentation.
+
+## LAYOUT-3 — Mỗi vùng một owner, mỗi trục scroll một owner
+
+Chi phối số thứ được phép nhận cùng một vùng hoặc cùng một trục tràn.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Nhiều vùng cùng tồn tại trên một trang | Mỗi vùng nhìn thấy được phân giải về đúng một composition owner và đúng một track chủ đích |
+| Case 2 | Nội dung rộng hơn cột của nó về bản chất, ví dụ một bảng | Đúng một `HorizontalScrollRegion` có tên sở hữu trục inline, và không tồn tại scroll ngang ở cấp trang |
+| Case 3 | Dòng chảy dọc cần bị chặn biên bên trong một vùng | `VerticalScrollRegion isScrollable`, hoặc đúng composition có tên đó, sở hữu trục dọc ấy |
+| Case 4 | Hội thoại phải scroll trong khi composer đứng yên | `ChatWorkspace` sở hữu scroll hội thoại, và composer là anh em của nó nằm ngoài scroller |
+| Case 5 | Có đề xuất lồng thêm một scroller | Mỗi scroller lồng nhau mang một trục có tên khác hoặc một nhiệm vụ có tên khác so với tổ tiên của nó |
+
+Không phải rule này: chuyện một vùng scroll có thật sự chạm tới và duyệt được bằng bàn phím sau khi
+render thuộc FOCUS-2.
+
+## LAYOUT-4 — Vùng rời khỏi dòng chảy bình thường
+
+Chi phối các vùng sticky, fixed, drawer, floating, bị đảo thứ tự thị giác, và vùng vắng mặt có điều
+kiện.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Cột bổ trợ cần nằm trong tầm mắt khi cột chính cuộn | `Rail mode="sticky"` mang biên đã công bố của nó, và dưới ngưỡng hẹp vùng đó trở lại dòng chảy bình thường |
+| Case 2 | Một overlay cần geometry fixed có biên | `WorkspaceShell.floatingLayer` chỉ cấp geometry; nếu còn cần giam focus và cách đóng, receipt gọi tên một modal owner hoặc ghi nhận gap |
+| Case 3 | Không gian hẹp không chứa nổi rail hội thoại theo dạng inline | `ChatWorkspace` sở hữu drawer, và receipt cấp `isRailOpen` cùng `onRailOpenChange` |
+| Case 4 | Một vùng vắng mặt ở trạng thái hiện tại | Không wrapper, track, divider, đường kẻ, spacer hay khoảng scroll đã đặt trước nào của vùng đó sống sót qua sự vắng mặt |
+| Case 5 | Direction muốn thứ tự thị giác khác đi ở một bề rộng | Thứ tự DOM, thứ tự đọc, thứ tự focus và thứ tự hành động trùng khít thứ tự nhiệm vụ ở mọi bề rộng; composition khác đi, thứ tự thì không |
+
+Không phải rule này: chuyện phần projection có thật sự chừa đủ chỗ cho nội dung bên dưới ở một
+viewport cụ thể là việc operator audit quan sát, không chốt ở đây.
+
+Retired: LAYOUT-5 đã 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
+
+Nội dung bên trong một vùng mang cấp độ nào thuộc [Hierarchy](hierarchy.vi.md). Một vùng tái bố cục
+ra sao khi không gian đổi thuộc [Responsive](responsive.vi.md). Action nào trong vùng là chủ đạo
+thuộc [CTA](cta.vi.md) và [Accent](accent.vi.md). Receipt phải liệt kê những gì về các vùng này
+thuộc [Coverage](coverage.vi.md). Chuyện kết quả render có khớp với direction này không là việc của
+operator audit, trong [Focus](../proof/focus.vi.md),
+[Accessibility](../proof/accessibility.vi.md), [Motion](../proof/motion.vi.md) và
+[Render truth](../proof/render-truth.vi.md).

package/knowledge/ui/composition/responsive.md

@@ -0,0 +1,67 @@
+# Responsive composition
+
+This file answers one question: as the space available to a task changes, what must survive, and
+which published query owns the change?
+
+Responsive decisions are made before any DOM exists, because they are decisions about which regions
+recompose, which branch disappears, and what the reader must still be able to do afterwards. A
+device name is never an answer here; the answer is always a named query on a named owner.
+
+## RESPONSIVE-1 — What survives when space shrinks
+
+Governs the floor the compact composition must keep.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A task must fit into markedly less space | The compact branch keeps the required meaning, the primary action, and the current state in one readable flow, and support remains reachable from it |
+| Case 2 | Content would otherwise force the page to scroll sideways | The composition recomposes; no clipping, no squeezing, and no page-level inline overflow appears in that branch |
+| Case 3 | A branch is hidden in compact space | The branch is genuinely absent, and a trigger with controlled state, focus return, and a recovery path stands in its place |
+| Case 4 | Parallel regions are wanted at a wider width | Every parallel region at that width resolves to a published composition that already offers the mode |
+| Case 5 | The required compact behaviour has no published composition | A `GRAMMAR_REQUIRED` gap names the missing behaviour, and no parallel breakpoint is authored in its place |
+
+## RESPONSIVE-2 — The query owner is named, not the device
+
+Governs which space is actually being observed.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A primary column sits beside a rail | The branch names the `PrimaryRailLayout` container query at inline-size `56rem` as its owner, so a narrow container stacks inside a wide window |
+| Case 2 | Shell regions recompose | Each `WorkspaceShell` boundary is named separately: the named-container queries at `72rem` and `56rem`, and the viewport rule at `69.999rem` |
+| Case 3 | Global navigation switches between full and compact | `NavigationFeatureNav` is named as the owner, observing the layout viewport around `48rem` |
+| Case 4 | A conversation rail switches between persistent and drawer | `ChatWorkspace` is named as the owner, observing the layout viewport through `matchMedia("(max-width: 47.999rem)")` alongside a CSS rule from `48rem` |
+| Case 5 | The direction wants a generic tablet breakpoint over these regions | No breakpoint outside the published owning queries governs those regions |
+
+Not this rule: which regions exist for the query to act on is LAYOUT-1.
+
+## RESPONSIVE-3 — Every compact branch has exactly one owner
+
+Governs who holds the state when a composition has two forms.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | `NavigationFeatureNav` exposes its compact trigger | The application owns the compact drawer through that extension point and supplies the same destinations, labels, state, focus return, and recovery |
+| Case 2 | `ChatWorkspace` switches its rail between persistent and drawer | The composition owns the switch; the receipt passes controlled state and callbacks only, and declares no listener of its own |
+| Case 3 | `PrimaryRailLayout` reflows a rail that is present | The published CSS owns the reflow, and a rail that is absent is absent in DOM rather than hidden |
+| Case 4 | Both forms would render and one is merely hidden | Exactly one branch exists at a time, and the other leaves no layout and no accessibility footprint |
+
+## RESPONSIVE-4 — Pressure that is not viewport width
+
+Governs the other ways space runs out.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | The reader zooms, enlarges text, or applies their own text spacing | The composition recomposes; no fixed text height and no clipping carries that pressure |
+| Case 2 | Copy grows because it was translated or because a state added words | The receipt names that growth inside the fit decision rather than as an exception to it |
+| Case 3 | Content is essentially two-dimensional and cannot reflow | Exactly one named `HorizontalScrollRegion` owns it, and the surrounding page stays inside its inline bound |
+| Case 4 | A virtual keyboard, an orientation change, or a safe-area inset reduces usable space | Persistent geometry still fits, stays visible, and occludes no part of the task; a layout query staying in wide mode is not accepted as proof of fit |
+| Case 5 | A state expands the surface, as an error, an expanded panel, or an overlay does | The expanded form is decided in the same receipt entry as the resting one |
+
+Retired: RESPONSIVE-5 is retired into COVERAGE-1 and is not reused; the address stays spent.
+
+## What this file does not decide
+
+Which regions exist and who owns their tracks is [Layout](layout.md). Whether meaning keeps its rank
+through a reflow is [Hierarchy](hierarchy.md), and whether an action group keeps its order is
+[CTA](cta.md). What the receipt must enumerate about these branches is [Coverage](coverage.md).
+Whether a compact branch is genuinely absent is decided in [State](state.md) and evidenced in
+[Focus](../proof/focus.md).

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

@@ -0,0 +1,67 @@
+# Responsive composition
+
+File này trả lời đúng một câu hỏi: khi không gian dành cho một nhiệm vụ thay đổi, cái gì phải sống
+sót, và query công khai nào sở hữu thay đổi đó.
+
+Quyết định responsive được đưa ra trước khi có DOM, vì chúng là quyết định về việc vùng nào tái bố
+cục, nhánh nào biến mất, và sau đó người đọc vẫn phải làm được gì. Một cái tên thiết bị không bao
+giờ là câu trả lời ở đây; câu trả lời luôn là một query có tên trên một owner có tên.
+
+## RESPONSIVE-1 — Cái gì sống sót khi không gian co lại
+
+Chi phối mức sàn mà bố cục hẹp phải giữ.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một nhiệm vụ phải lọt vào không gian nhỏ hơn hẳn | Nhánh hẹp giữ nguyên ý nghĩa bắt buộc, action chính và trạng thái hiện tại trong một luồng đọc được, và phần bổ trợ vẫn chạm tới được từ đó |
+| Case 2 | Nội dung sẽ khiến cả trang phải cuộn ngang | Composition tái bố cục; trong nhánh đó không có cắt xén, không có bóp lại và không có tràn inline ở cấp trang |
+| Case 3 | Một nhánh bị ẩn đi trong không gian hẹp | Nhánh đó vắng mặt thật sự, và thay chỗ nó là một trigger có state điều khiển được, có đường trả focus và có lối phục hồi |
+| Case 4 | Muốn có các vùng song song ở bề rộng lớn hơn | Mọi vùng song song ở bề rộng đó phân giải về một composition công khai vốn đã có sẵn chế độ ấy |
+| Case 5 | Hành vi hẹp cần dùng chưa có composition công khai nào | Một gap `GRAMMAR_REQUIRED` gọi tên hành vi còn thiếu, và không breakpoint song song nào được tự dựng thay chỗ nó |
+
+## RESPONSIVE-2 — Gọi tên owner của query, không gọi tên thiết bị
+
+Chi phối việc không gian nào thật sự đang được quan sát.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một cột chính nằm cạnh một rail | Nhánh đó gọi tên container query của `PrimaryRailLayout` ở inline-size `56rem` làm owner, nên một container hẹp vẫn xếp chồng bên trong cửa sổ rộng |
+| Case 2 | Các vùng shell tái bố cục | Mỗi ngưỡng của `WorkspaceShell` được gọi tên riêng: container query có tên ở `72rem` và `56rem`, và rule theo viewport ở `69.999rem` |
+| Case 3 | Navigation toàn cục đổi giữa dạng đầy đủ và dạng gọn | `NavigationFeatureNav` được gọi tên là owner, quan sát layout viewport quanh mốc `48rem` |
+| Case 4 | Rail hội thoại đổi giữa dạng thường trực và drawer | `ChatWorkspace` được gọi tên là owner, quan sát layout viewport qua `matchMedia("(max-width: 47.999rem)")` đi kèm một rule CSS từ `48rem` |
+| Case 5 | Direction muốn một breakpoint tablet chung phủ lên các vùng này | Không breakpoint nào ngoài các query sở hữu đã công bố chi phối những vùng đó |
+
+Không phải rule này: trang có những vùng nào để query tác động lên thuộc LAYOUT-1.
+
+## RESPONSIVE-3 — Mỗi nhánh hẹp có đúng một owner
+
+Chi phối việc ai giữ state khi một composition có hai hình dạng.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | `NavigationFeatureNav` để lộ trigger dạng gọn của nó | Ứng dụng sở hữu drawer gọn qua extension point đó và cấp đúng những điểm đến, nhãn, state, đường trả focus và lối phục hồi ấy |
+| Case 2 | `ChatWorkspace` đổi rail giữa thường trực và drawer | Composition sở hữu việc đổi; receipt chỉ truyền state điều khiển và callback, và không khai báo listener nào của riêng nó |
+| Case 3 | `PrimaryRailLayout` tái bố cục một rail đang hiện diện | CSS công khai sở hữu việc tái bố cục, còn một rail vắng mặt thì vắng mặt trong DOM chứ không bị ẩn |
+| Case 4 | Cả hai hình dạng cùng render và một cái chỉ bị ẩn | Mỗi lúc tồn tại đúng một nhánh, và nhánh kia không để lại dấu vết layout hay accessibility nào |
+
+## RESPONSIVE-4 — Áp lực không đến từ bề rộng viewport
+
+Chi phối những cách khác khiến không gian cạn đi.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Người đọc zoom, phóng chữ, hoặc tự đặt text spacing | Composition tái bố cục; không chiều cao chữ cố định và không cắt xén nào gánh áp lực đó |
+| Case 2 | Copy dài ra vì đã dịch hoặc vì một state thêm chữ | Receipt gọi tên phần dài ra ngay trong quyết định vừa vặn, chứ không như một ngoại lệ của nó |
+| Case 3 | Nội dung vốn hai chiều và không thể chảy lại | Đúng một `HorizontalScrollRegion` có tên sở hữu nó, và trang bao quanh vẫn nằm trong biên inline của mình |
+| Case 4 | Bàn phím ảo, xoay màn hình hoặc safe-area làm hụt không gian dùng được | Geometry thường trực vẫn vừa, vẫn nhìn thấy và không che phần nào của nhiệm vụ; việc một layout query vẫn ở chế độ rộng không được nhận là bằng chứng vừa mắt |
+| Case 5 | Một state làm surface nở ra, như lỗi, panel mở hay overlay | Hình dạng nở ra được chốt trong cùng mục receipt với hình dạng lúc nghỉ |
+
+Retired: RESPONSIVE-5 đã 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
+
+Trang có những vùng nào và ai sở hữu track thuộc [Layout](layout.vi.md). Ý nghĩa có giữ được cấp độ
+qua một lần reflow không thuộc [Hierarchy](hierarchy.vi.md), còn một nhóm action có giữ được thứ tự
+không thuộc [CTA](cta.vi.md). Receipt phải liệt kê những gì về các nhánh này thuộc
+[Coverage](coverage.vi.md). Một nhánh hẹp có vắng mặt thật sự hay không được chốt ở
+[State](state.vi.md) và được chứng minh ở [Focus](../proof/focus.vi.md).

package/knowledge/ui/composition/state.md

@@ -0,0 +1,105 @@
+# State composition
+
+This file answers one question: which distinct conditions can this feature be in, and which
+published carrier holds each one?
+
+State is compiled before anything renders. The direction lists the business facts and the
+transitions between them first, then binds each to a real carrier. Two facts that share a carrier
+become one fact, and a fact with no carrier becomes a guess, so the compiling step is the rule.
+
+## The five kinds
+
+| Kind | Examples | Nature |
+| --- | --- | --- |
+| Transient cue | hover, focus, pressed | Lasts only while the input lasts |
+| Persistent value | selected, expanded | Survives blur, rerender, and reflow |
+| Lifecycle fact | unavailable, pending, initially unresolved | Follows the work, not the pointer |
+| Settled outcome | success, error, cancellation | Requires a real result from authority |
+| Absence | the branch does not exist | Contributes nothing at all |
+
+`PresentationState` publishes `neutral`, `informative`, `affirmative`, `cautionary`, `negative`,
+`pending`, and `unavailable` for owners such as surfaces, rails, and static rows. Those values are
+render-neutral: they paint a fact that authority already established, and they never create one.
+
+## STATE-1 — Name the meanings before choosing carriers
+
+Governs the order in which state decisions are made.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A feature has more than one reachable condition | Every business fact and every transition between them is named in the receipt before any carrier prop appears against it |
+| Case 2 | The named facts are ready to bind | Each named fact resolves to its own carrier: `isDisabled`, `isPending`, or `isSkeleton` where the owner publishes them, `Tabs.selectedKey`, `SurfaceAccordionCard.isOpen`, or a `PresentationState` on its owner |
+| Case 3 | A single generic flag would cover several of them | No carrier appears against more than one named fact, so disabled, pending, and unresolved never share one flag |
+| Case 4 | A transient cue is available and looks convenient | No hover or focus cue carries a selected or expanded value |
+| Case 5 | A presentation value is available before authority has spoken | Every `PresentationState` value in the tree traces to a fact authority already settled; none precedes it |
+
+## STATE-2 — Accepted work and unresolved content have separate owners
+
+Governs the boundary between progress and loading.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | A command accepted work | `isPending` sits on the initiating command, or on the published forwarding prop such as `EmptyNotice.isActionPending` |
+| Case 2 | Content has not resolved for the first time | `isSkeleton` sits on the content owner, and that owner renders inert geometry with no announced value |
+| Case 3 | A measurement is unknown | No node states a value for it; a rendered zero appears nowhere in place of an unknown measurement |
+| Case 4 | A peer control did not start the work | That control carries no progress cue of its own |
+
+Not this rule: what the reader is told once the work settles is FEEDBACK-3.
+
+## STATE-3 — Absence is complete
+
+Governs what a branch leaves behind when it does not exist.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | Authority says an optional branch, control, region, or slot does not exist now | The branch is unmounted through the published optional contract, such as an omitted `ChatWorkspace` rail or an omitted `EmptyNotice.actionLabel` |
+| Case 2 | Hiding it visually would be easier | No node for that branch remains in the tree, visible or not, and nothing invisible still responds to input |
+| Case 3 | The branch sat inside a grid or a flex row | Its wrapper, track, spacer, divider, and reserved scroll range are absent with it |
+| Case 4 | The branch contained anything focusable | Nothing from that branch is focusable and nothing from it appears in the accessibility tree |
+
+Retired: STATE-4 is retired into COVERAGE-1 and is not reused; the address stays spent.
+
+## STATE-5 — Whole-surface action or static surface
+
+Governs whether a surface is itself one interactive thing.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | The entire surface leads to one destination | `SurfaceCard.wholeAction` is `{ kind: "link", href, label }`, giving exactly one semantic target with one accessible name |
+| Case 2 | The entire surface runs one command | `SurfaceCard.wholeAction` is `{ kind: "button", press, label }` |
+| Case 3 | The surface is not interactive | `wholeAction` is absent, and the surface carries no click handler and no hover response that implies interaction |
+| Case 4 | The surface needs a smaller independent action inside it, such as a row menu | The whole-surface target and the smaller action occupy disjoint boundaries; neither encloses the other |
+
+Not this rule: how many effects one activation may reach is ACTION-1.
+
+## STATE-6 — Persistent peer choice
+
+Governs a selected value shared by peer views.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | Peer views share one selection that must outlive hover, press, and focus | `Tabs` carries an application-owned `selectedKey` with ordered `items` and `onSelect` |
+| Case 2 | Each peer controls a panel | `panelId` associates each tab with its panel, so the relationship is published rather than implied |
+| Case 3 | The direction is tempted to keep a second selected value locally | Exactly one controlled value drives the rendering; no local copy of that selection exists |
+| Case 4 | The direction is tempted to wrap the published tabs in its own tab roles | No node outside `Tabs` carries composite tab semantics for the same choice |
+
+## STATE-7 — Controlled disclosure
+
+Governs a summary that reveals a region.
+
+| Case | When | Assert |
+| --- | --- | --- |
+| Case 1 | One summary reveals or hides one associated region | `SurfaceAccordionCard` carries `isOpen`, `summaryRender`, `bodyRender`, and `onOpenChange` |
+| Case 2 | A list has several independently controlled disclosures | Controlled `items` with `onItemOpenChange` bind each open value to its own item |
+| Case 3 | Hover would open it, or a second trigger would sit beside the published one | Disclosure changes only through the controlled value, from exactly one trigger; no hover path and no second trigger reaches it |
+| Case 4 | The closed body contains links or controls | While closed, nothing inside the body is focusable or announced |
+
+## What this file does not decide
+
+Which regions exist to hold these states is [Layout](layout.md), and which branch survives a reflow
+is [Responsive](responsive.md). Which control carries a decision, and who owns pending among several
+controls, is [CTA](cta.md) and [Action](action.md). What the reader is told at each outcome is
+[Feedback](feedback.md). What the receipt must enumerate about these states is
+[Coverage](coverage.md). Whether the rendered state is announced, reachable, and truthful is
+[Accessibility](../proof/accessibility.md), [Focus](../proof/focus.md), and
+[Render truth](../proof/render-truth.md).

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

@@ -0,0 +1,106 @@
+# State composition
+
+File này trả lời đúng một câu hỏi: tính năng này có thể rơi vào những điều kiện riêng biệt nào, và
+carrier công khai nào giữ từng điều kiện đó.
+
+State được biên dịch trước khi bất cứ thứ gì render. Direction liệt kê các dữ kiện business và các
+bước chuyển giữa chúng trước, rồi mới gán từng cái vào một carrier thật. Hai dữ kiện dùng chung một
+carrier sẽ hoá thành một dữ kiện, còn một dữ kiện không có carrier thì hoá thành phỏng đoán, nên
+chính bước biên dịch đó mới là rule.
+
+## Năm loại
+
+| Loại | Ví dụ | Bản chất |
+| --- | --- | --- |
+| Dấu hiệu thoáng qua | hover, focus, pressed | Chỉ tồn tại chừng nào thao tác còn tồn tại |
+| Giá trị bền vững | selected, expanded | Sống sót qua blur, qua rerender và qua reflow |
+| Dữ kiện vòng đời | không dùng được, đang chạy, chưa giải quyết lần đầu | Đi theo công việc, không đi theo con trỏ |
+| Kết cục đã chốt | thành công, lỗi, huỷ | Đòi một kết quả thật từ authority |
+| Vắng mặt | nhánh đó không tồn tại | Không đóng góp gì hết |
+
+`PresentationState` công bố `neutral`, `informative`, `affirmative`, `cautionary`, `negative`,
+`pending` và `unavailable` cho các owner như surface, rail và static row. Các giá trị đó trung tính
+về mặt render: chúng sơn một dữ kiện mà authority đã xác lập, và không bao giờ tự tạo ra dữ kiện.
+
+## STATE-1 — Gọi tên các ý nghĩa trước khi chọn carrier
+
+Chi phối thứ tự đưa ra quyết định về state.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một tính năng có hơn một điều kiện chạm tới được | Mọi dữ kiện business và mọi bước chuyển giữa chúng đã có tên trong receipt trước khi bất kỳ prop carrier nào đứng cạnh chúng |
+| Case 2 | Các dữ kiện đã sẵn sàng để gán | Mỗi dữ kiện đã đặt tên phân giải về carrier riêng của nó: `isDisabled`, `isPending` hoặc `isSkeleton` ở nơi owner có công bố chúng, `Tabs.selectedKey`, `SurfaceAccordionCard.isOpen`, hoặc một `PresentationState` trên owner của nó |
+| Case 3 | Một cờ chung có thể phủ được vài dữ kiện cùng lúc | Không carrier nào đứng cho quá một dữ kiện, nên disabled, pending và chưa giải quyết không bao giờ chung một cờ |
+| Case 4 | Có sẵn một dấu hiệu thoáng qua trông rất tiện | Không có dấu hiệu hover hay focus nào mang giá trị selected hoặc expanded |
+| Case 5 | Một giá trị presentation có sẵn trước khi authority lên tiếng | Mọi giá trị `PresentationState` trong cây đều truy về một dữ kiện authority đã chốt; không giá trị nào đi trước nó |
+
+## STATE-2 — Việc đã nhận và nội dung chưa giải quyết có owner khác nhau
+
+Chi phối ranh giới giữa tiến trình và tải nội dung.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một câu lệnh đã nhận việc | `isPending` nằm trên chính câu lệnh khởi động, hoặc trên prop chuyển tiếp công khai như `EmptyNotice.isActionPending` |
+| Case 2 | Nội dung chưa giải quyết lần đầu | `isSkeleton` nằm trên owner của nội dung, và owner đó cho ra hình khối trơ, không giá trị nào được đọc lên |
+| Case 3 | Một phép đo chưa biết | Không node nào nêu giá trị cho nó, và không có số không nào được render thay cho một phép đo chưa biết |
+| Case 4 | Một control ngang hàng không khởi động việc đó | Control đó không mang dấu hiệu tiến trình nào của riêng nó |
+
+Không phải rule này: người đọc được nói gì khi việc kết thúc thuộc FEEDBACK-3.
+
+## STATE-3 — Vắng mặt phải vắng mặt trọn vẹn
+
+Chi phối thứ mà một nhánh để lại khi nó không tồn tại.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Authority nói rằng một nhánh, control, vùng hay slot tuỳ chọn hiện không tồn tại | Nhánh đó không được mount, qua hợp đồng tuỳ chọn công khai, chẳng hạn rail của `ChatWorkspace` bị bỏ hoặc `EmptyNotice.actionLabel` bị bỏ |
+| Case 2 | Ẩn nó đi bằng thị giác thì dễ hơn | Không node nào của nhánh đó còn trong cây, dù nhìn thấy hay không, và không thứ vô hình nào còn phản hồi thao tác |
+| Case 3 | Nhánh đó từng nằm trong một grid hoặc một hàng flex | Wrapper, track, spacer, divider và khoảng scroll đã đặt trước đều vắng mặt cùng nó |
+| Case 4 | Nhánh đó từng chứa thứ gì focus được | Không gì từ nhánh đó focus được và không gì từ nó xuất hiện trong accessibility tree |
+
+Retired: STATE-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.
+
+## STATE-5 — Surface là một action, hoặc là tĩnh
+
+Chi phối việc một surface có tự nó là một thứ tương tác hay không.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Toàn bộ surface dẫn tới một điểm đến | `SurfaceCard.wholeAction` là `{ kind: "link", href, label }`, cho ra đúng một mục tiêu ngữ nghĩa với một tên khả truy cập |
+| Case 2 | Toàn bộ surface chạy một câu lệnh | `SurfaceCard.wholeAction` là `{ kind: "button", press, label }` |
+| Case 3 | Surface không tương tác | `wholeAction` vắng mặt, và surface không mang click handler hay phản hồi hover nào gợi ra sự tương tác |
+| Case 4 | Surface cần một action nhỏ độc lập bên trong, ví dụ menu của một hàng | Mục tiêu toàn surface và action nhỏ nằm trên hai ranh giới rời nhau; không cái nào bọc cái nào |
+
+Không phải rule này: một lần kích hoạt chạm tới bao nhiêu hiệu ứng thuộc ACTION-1.
+
+## STATE-6 — Lựa chọn bền vững giữa các view ngang hàng
+
+Chi phối một giá trị selected mà các view ngang hàng dùng chung.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Các view ngang hàng dùng chung một lựa chọn phải sống lâu hơn hover, press và focus | `Tabs` mang `selectedKey` do ứng dụng sở hữu, cùng `items` có thứ tự và `onSelect` |
+| Case 2 | Mỗi view ngang hàng điều khiển một panel | `panelId` gắn mỗi tab với panel của nó, nên quan hệ đó được công bố chứ không ngầm hiểu |
+| Case 3 | Direction bị cám dỗ giữ thêm một giá trị selected cục bộ | Đúng một giá trị điều khiển lái phần render; không tồn tại bản sao cục bộ của lựa chọn đó |
+| Case 4 | Direction bị cám dỗ bọc thêm role tab của riêng mình quanh tabs công khai | Không node nào ngoài `Tabs` mang ngữ nghĩa tab composite cho cùng lựa chọn đó |
+
+## STATE-7 — Disclosure có điều khiển
+
+Chi phối một phần tóm tắt làm hiện ra một vùng.
+
+| Case | Dùng khi | Khẳng định |
+| --- | --- | --- |
+| Case 1 | Một phần tóm tắt làm hiện hoặc ẩn một vùng gắn với nó | `SurfaceAccordionCard` mang `isOpen`, `summaryRender`, `bodyRender` và `onOpenChange` |
+| Case 2 | Một danh sách có nhiều disclosure điều khiển độc lập | `items` có điều khiển cùng `onItemOpenChange` gắn mỗi giá trị open vào đúng item của nó |
+| Case 3 | Hover sẽ mở nó ra, hoặc có thêm một trigger thứ hai nằm cạnh trigger công khai | Disclosure chỉ đổi qua giá trị điều khiển, từ đúng một trigger; không đường hover nào và không trigger thứ hai nào chạm tới nó |
+| Case 4 | Phần thân đang đóng có chứa link hoặc control | Khi đóng, không gì bên trong phần thân focus được hay được đọc lên |
+
+## File này không quyết định
+
+Trang có những vùng nào để chứa các state này thuộc [Layout](layout.vi.md), và nhánh nào sống sót
+qua reflow thuộc [Responsive](responsive.vi.md). Control nào mang quyết định, và khi nhiều control
+cùng tham gia thì ai giữ pending, thuộc [CTA](cta.vi.md) và [Action](action.vi.md). Người đọc được
+nói gì ở mỗi kết cục thuộc [Feedback](feedback.vi.md). Receipt phải liệt kê những gì về các state
+này thuộc [Coverage](coverage.vi.md). State sau khi render có được đọc lên, có chạm tới được và có
+đúng sự thật không thuộc [Accessibility](../proof/accessibility.vi.md),
+[Focus](../proof/focus.vi.md) và [Render truth](../proof/render-truth.vi.md).

package/knowledge/ui/presentation/INDEX.md

@@ -0,0 +1,94 @@
+# UI presentation
+
+Presentation is the last UI decision layer:
+
+```text
+business
+-> composition chooses the DOM structure, layout and Grammar objects
+-> presentation resolves CSS values on app-owned boundaries
+-> rendered UI
+```
+
+Rules in this folder are conditionally mandatory: when a rule's `When` matches, the presentation
+must use that rule or preserve an equivalent value already supplied by the public Grammar API.
+
+## Authority
+
+Presentation may:
+
+- set relationships between already-chosen Grammar objects;
+- style an app-owned page, section, container or content-region boundary;
+- choose public `Text` and `Heading` hierarchy props from business information rank;
+- resolve wrapping, measure and overflow for app-owned content.
+
+Presentation must not:
+
+- choose or rebuild the DOM structure, flex/grid layout or Grammar component;
+- add padding, typography or paint inside `Card`, `Input`, `Button` or another Grammar object;
+- reach through a Grammar component with selectors or consumer classes;
+- decide responsive transformation, CTA priority, state, focus or motion; those belong to other
+  knowledge groups.
+
+Layout classes may appear in examples because composition has already chosen them. Their presence
+is context, not a presentation recommendation.
+
+## Catalog
+
+| Knowledge | Properties it decides | Rules |
+| --- | --- | --- |
+| [Gap](gap.md) | `gap`, `row-gap`, `column-gap` between Grammar objects | GAP-0 to GAP-6 |
+| [Padding](padding.md) | Inset of app-owned pages, sections, and containers | PADDING-0 to PADDING-9 |
+| [Margin](margin.md) | External offset and auto placement, as a named exception; gap comes first | MARGIN-0 to MARGIN-6, MARGIN-AUTO |
+| [Font](font.md) | `font-size`, `font-weight`, `line-height`, `letter-spacing` by title, body, and meta rank | FONT-1 to FONT-6, plus weight |
+| [Tone](tone.md) | Default, muted, and accent by information rank; never a raw colour | TONE-1 to TONE-3 |
+| [Surface](surface.md) | Which semantic surface an app-owned region takes, with its paired foreground | SURFACE-1 to SURFACE-6 |
+| [Boundary](boundary.md) | Which separator or border draws an app-owned edge, and which edge drops it | BOUNDARY-1 to BOUNDARY-6 |
+| [Measure](measure.md) | `width`, `height`, and their minima and maxima for app-owned regions | MEASURE-1 to MEASURE-7 |
+| [Text flow](text-flow.md) | `text-align`, wrapping, `white-space`, truncation, line clamping | FLOW-1 to FLOW-5 |
+| [Overflow](overflow.md) | Scroll, clip, and containment boundaries owned by the app | OVERFLOW-1 to OVERFLOW-5 |
+
+Gap, padding, and margin share `COMMON_SPACING_SCALE`, so their rule numbers are ordinal positions on
+that one closed scale. Font and tone have their own closed scales. Measure, surface, boundary, text
+flow, and overflow have no value ramp, so their numbers address constraint kinds instead, and each
+file says so.
+
+## Rule shape
+
+`GAP-1`, `FONT-1`, and the other `PREFIX-n` names are stable ordinal addresses on their topic's closed
+value scale. `GAP-1` is the first gap value, not a severity, component variant, or Tailwind step. The
+ID and the class agree only while the scale and the Tailwind steps happen to run together; where they
+diverge, the ID keeps counting and the class does not. Every heading therefore prints both, as
+`## GAP-5 — gap-6 / 1.5rem`, and every topic opens with a scale table mapping rule to class to value,
+naming the classes that fall outside the scale.
+
+A rule is one value. Its cases are the situations that resolve to it, selected by an observable
+property of the already-rendered tree. Two cases never describe the same situation.
+
+Every rule contains its heading, one line naming the relationship the value expresses, and one table:
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | The concrete condition that selects this value. | Who owns the distance. | Inline TSX, or nothing when a component owns it. |
+
+The owner cell is one of three values, and every topic states them once near the top:
+
+- `App`, so the application writes the class on its own container.
+- A Common component name, so the distance already lives inside that component. The application
+  passes a prop and writes no class. Writing it anyway is `APP_REIMPLEMENTATION`.
+- `—`, so Common exposes no public path. The class is a recorded workaround linked to
+  `COMMON_CAPABILITY_MISSING`.
+
+Each topic also carries one table of the relationships Common already owns, mapping component to the
+element or prop condition that carries the claim, to rule, so a reader can rule out writing anything
+before reaching the cases. That table is generated from the `data-contract` claims the package
+publishes, by `scripts/generate-presentation-owned.mjs`, so it is never edited by hand: a wrong row
+is repaired in the component. A case below it is added only when two authorized evidence blocks show
+the situation, the same evidence rule the family idioms use; one occurrence is a product decision,
+not a rule.
+
+A case belonging to a neighbouring value is not a table row. It goes on one line after the table, as
+`Not this rule: <condition> uses GAP-n`.
+
+Add `Case 2`, `Case 3`, and further rows only for materially different situations governed by the same
+value. Code stays in the table. Do not add `Why`, `When not to use`, detached code blocks, audit
+verdicts, imagined APIs, placeholder examples, or paragraphs about values that are not on the scale.

package/knowledge/ui/presentation/INDEX.vi.md

@@ -0,0 +1,69 @@
+# UI presentation
+
+Presentation là tầng quyết định UI cuối cùng:
+
+```text
+business
+-> composition chọn cấu trúc DOM, layout và Grammar object
+-> presentation chốt giá trị CSS trên boundary do app sở hữu
+-> UI đã render
+```
+
+Các rule trong folder này là bắt buộc có điều kiện: khi phần `Khi nào` khớp, presentation phải dùng
+rule đó hoặc giữ giá trị tương đương đã được public Grammar API cung cấp.
+
+## Authority
+
+Presentation được phép:
+
+- đặt quan hệ giữa các Grammar object đã được composition chọn;
+- style boundary page, section, container hoặc content region do app sở hữu;
+- chọn public prop của `Text` và `Heading` dựa trên cấp độ thông tin business;
+- chốt wrapping, measure và overflow cho content do app sở hữu.
+
+Presentation không được:
+
+- chọn lại hoặc dựng lại cấu trúc DOM, flex/grid layout hay Grammar component;
+- thêm padding, typography hoặc paint vào bên trong `Card`, `Input`, `Button` hay Grammar object khác;
+- reach-through vào Grammar component bằng selector hoặc consumer class;
+- quyết định responsive transformation, CTA priority, state, focus hay motion; chúng thuộc nhóm
+  knowledge khác.
+
+Layout class có thể xuất hiện trong ví dụ vì composition đã chọn chúng từ trước. Chúng chỉ là context,
+không phải recommendation của presentation.
+
+## Danh mục
+
+| Quyết định | Knowledge |
+| --- | --- |
+| Khoảng cách giữa các object đã ghép | [Gap](gap.vi.md) |
+| Inset page/section/container của app | [Padding](padding.vi.md) |
+| External offset ngoại lệ hoặc auto placement | [Margin](margin.vi.md) |
+| Cấp độ size, weight và heading | [Font](font.vi.md) |
+| Nhấn mạnh text default, muted và accent | [Tone](tone.vi.md) |
+| Surface ngữ nghĩa của vùng do app sở hữu, kèm foreground đi cặp | [Surface](surface.vi.md) |
+| Separator hay border vẽ cạnh do app sở hữu, và cạnh nào bỏ đường kẻ | [Boundary](boundary.vi.md) |
+| Giới hạn width và height của content region | [Measure](measure.vi.md) |
+| Wrapping, alignment và truncation | [Text flow](text-flow.vi.md) |
+| Scroll và clipping boundary do app sở hữu | [Overflow](overflow.vi.md) |
+
+## Cấu trúc rule
+
+`GAP-1`, `FONT-1` và các tên `PREFIX-n` khác là địa chỉ thứ tự ổn định. Con số không phải bước
+Tailwind, giá trị CSS, component variant hay mức độ nghiêm trọng.
+
+Bảng "Common đã sở hữu" trong mỗi topic được sinh ra từ claim `data-contract` mà package công bố,
+bằng `scripts/generate-presentation-owned.mjs`, nên không ai sửa tay: một hàng sai thì sửa component,
+không sửa bảng. Một case bên dưới bảng chỉ được thêm khi hai block bằng chứng được uỷ quyền cùng cho
+thấy tình huống đó, đúng luật bằng chứng mà các idiom của family đang dùng; xuất hiện một lần là
+quyết định sản phẩm, chưa phải rule.
+
+Mỗi rule chỉ có heading và đúng một bảng:
+
+| Case | When | Common render |
+| --- | --- | --- |
+| Case 1 | Điều kiện cụ thể chọn rule. | TSX inline qua API public hiện có của `@starci/grammar/common`, kèm prop, class hoặc giá trị đã resolve khi source chứng minh được. |
+
+Chỉ thêm `Case 2`, `Case 3` và các row tiếp theo khi chúng là những đầu vào khác nhau nhưng cùng một
+quyết định. Code nằm trong bảng. Không thêm `Why`, `When not to use`, code block rời, audit verdict,
+API tưởng tượng hay ví dụ placeholder.