@starci/skills 1.1.0

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

@@ -0,0 +1,171 @@
+# Margin presentation
+
+File này trả lời đúng một câu hỏi: khi nào một object do ứng dụng sở hữu được phép đẩy ra khỏi xung
+quanh bằng một khoảng lệch ngoài, và lệch bao nhiêu.
+
+Margin là ngoại lệ trong hệ này chứ không phải mặc định. Khoảng cách giữa các phần tử ngang hàng
+thuộc về gap của cha, còn khoảng cách từ ranh giới tới nội dung thuộc về padding của chính ranh giới
+đó. Margin chỉ đúng khi một object cần một khoảng lệch mà không quan hệ cha nào diễn đạt được, và lý
+do đó phải gọi được tên.
+
+Common phản ánh đúng như vậy: nó reset `margin` về `0` ở gần như mọi renderer nó sở hữu và để cha
+nắm nhịp. Ứng dụng nào với tay tới margin trước là tạo ra hai chủ cho cùng một khoảng cách, tức
+`DOUBLE_OWNER`.
+
+## Thang giá trị
+
+`COMMON_SPACING_SCALE` là thang đóng. Số của rule là thứ tự trên thang đó. Nó không phải số bậc
+Tailwind, và hai số này lệch nhau từ MARGIN-5 trở đi.
+
+| Rule | Class | Giá trị | Token Common |
+| --- | --- | --- | --- |
+| MARGIN-0 | `m-0` | `0` | không có |
+| MARGIN-1 | `m-1` | `.25rem` | không có |
+| MARGIN-2 | `m-2` | `.5rem` | không có |
+| MARGIN-3 | `m-3` | `.75rem` | không có |
+| MARGIN-4 | `m-4` | `1rem` | không có |
+| MARGIN-5 | `m-6` | `1.5rem` | không có |
+| MARGIN-6 | `m-8` | `2rem` | không có |
+
+Common không publish token margin nào. `MARGIN-AUTO` đứng riêng và không mang giá trị nào trên thang.
+
+Các giá trị rem chỉ quy ra `0 / 4 / 8 / 12 / 16 / 24 / 32` pixel CSS khi root font size tính được là
+`16px`. Khi kiểm tra lúc chạy thì dùng `expectedPx = remFactor * observedRootFontPx`.
+
+## Owner
+
+Mỗi case gọi tên ai sở hữu khoảng lệch. Owner quyết định ứng dụng có được viết class hay không.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Khoảng lệch là một ngoại lệ đặt chỗ có tên của ứng dụng | Viết class |
+| Tên component | Common đã đặt hoặc reset margin bên trong component đó | Không viết gì, chỉ ghép component |
+| `—` | Common chưa có đường dùng công khai cho quan hệ này | Viết class, ghi nhận là workaround |
+
+Viết class ở chỗ owner là một component chính là `APP_REIMPLEMENTATION`. Thêm margin cho con trong
+khi cha đã có gap diễn đạt đúng khoảng cách đó là `DOUBLE_OWNER`.
+
+## Margin mà Common đã sở hữu
+
+Sinh từ claim của `@grammar/core` bằng `scripts/generate-presentation-owned.mjs`; muốn đổi thì sửa component, đừng sửa bảng này.
+
+| Component | Phần tử hoặc điều kiện | Rule |
+| --- | --- | --- |
+| `Label` | root | MARGIN-0 |
+| `MediaFrame` | root | MARGIN-0 |
+| `PageContainer` | root | MARGIN-AUTO |
+| `SectionHeader` | title | MARGIN-0 |
+| `SurfaceAccordionCard` | accordion trigger wrapper | MARGIN-0 |
+| `WorkspaceShell` | header, hasHeader | MARGIN-5 |
+
+## MARGIN-0 — `m-0` / `0`
+
+Khoảng lệch bị gỡ đi để một quan hệ của cha trở thành chủ duy nhất của khoảng cách.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một thẻ HTML mang margin mặc định chọi lại composition | `App` | `<h2 className="m-0">` trong section app đã tự nắm gap |
+| Case 2 | Nội dung article đã render, nhịp do chính article nắm | `MarkdownArticle` | Ghép article, không viết margin |
+| Case 3 | Bất kỳ renderer Common nào đã tự reset margin của nó | Chính component đó | Ghép nó, không viết margin |
+
+Không phải rule này: xóa một khoảng lệch có chủ ý mà không chuyển quyết định đó cho một chủ thật sự
+thì quan hệ đó thành vô chủ.
+
+## MARGIN-1 — `m-1` / `.25rem`
+
+Khoảng hở ngoài nhỏ nhất, cho một object đặt chính xác mà chỉ cần vừa đủ rời khỏi mép.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một nhãn đặt tuyệt đối, nếu không lệch thì chạm luôn vào mép khung chứa | `App` | `<span className="absolute left-0 top-0 m-1">` |
+
+Không phải rule này: lặp lại trên nhiều phần tử ngang hàng là đang dựng lại một cái gap. Dùng GAP-1
+trên cha.
+
+## MARGIN-2 — `m-2` / `.5rem`
+
+Khoảng lệch gọn cho một object đặt độc lập.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Chú thích hoặc control phủ lên, neo vào một góc canvas do app sở hữu | `App` | `<aside className="absolute bottom-0 right-0 m-2">` |
+
+Không phải rule này: dùng thay cho padding của container hoặc gap giữa các phần tử. Dùng PADDING-2
+hoặc GAP-2.
+
+## MARGIN-3 — `m-3` / `.75rem`
+
+Khoảng lệch dày dặn nhưng vẫn thấy rõ, cho một ngoại lệ đặt chỗ có tên.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một object đặt trên nền nhiều chi tiết, để `.5rem` thì đọc thành chật | `App` | `<aside className="absolute right-0 top-0 m-3">` |
+
+Không phải rule này: các mục lặp lại trong một danh sách. Dùng GAP-3 trên cha.
+
+## MARGIN-4 — `m-4` / `1rem`
+
+Khoảng lệch ngoài chuẩn cho một object có ngoại lệ đặt chỗ tường minh.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một object đứng riêng cần khoảng hở đều với khung chứa mà khung đó không sở hữu được | `App` | `<aside className="m-4">` |
+| Case 2 | Khoảng trống phía sau một khối code trong nội dung article | `FencedCodeBlock` | Ghép khối, không viết margin |
+| Case 3 | Nhịp trục block quanh một đường kẻ ngang trong nội dung article | `MarkdownArticle` | Ghép article, không viết margin |
+
+Không phải rule này: ghép nó với padding của cha cho cùng một mục đích mép tới nội dung là tạo hai
+chủ cho một khoảng cách.
+
+## MARGIN-5 — `m-6` / `1.5rem`
+
+Khoảng lệch lớn, làm một object đứng riêng tách hẳn khỏi khung chứa của nó.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một ngoại lệ có tên cần rời khỏi ranh giới xa hơn mức lệch chuẩn | `App` | `<aside className="m-6">` |
+| Case 2 | Khoảng tách bên dưới header của một workspace | `WorkspaceShell` | Ghép shell, không viết margin |
+
+Không phải rule này: khoảng tách giữa các phần tử ngang hàng cỡ lớn. Dùng GAP-5 trên cha.
+
+## MARGIN-6 — `m-8` / `2rem`
+
+Khoảng hở ngoài lớn nhất, cho một object cố ý tách rời.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một object phải đọc lên là tách khỏi mọi thứ quanh nó, và có lý do nói được | `App` | `<aside className="m-8">` |
+
+Không phải rule này: nhịp chung của trang, hoặc lặp lại trên nhiều phần tử ngang hàng. Dùng GAP-6
+trên cha.
+
+## MARGIN-AUTO — `mx-auto`
+
+Margin ngang tự động chia đều khoảng trống còn lại và canh giữa một container đã giới hạn chiều rộng.
+Nó không mang giá trị nào trên thang và không phải một quyết định về khoảng lệch.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một container do app sở hữu, tự giới hạn chiều rộng và phải nằm giữa | `App` | `<main className="mx-auto max-w-3xl">` |
+| Case 2 | Một trang dùng khổ và inset đóng gói sẵn | `PageContainer` | Ghép container, nó đã canh giữa sẵn |
+
+Không phải rule này: một phần tử rộng hết khung, hoặc dùng để rải đều khoảng cách giữa các phần tử.
+Việc rải đều thuộc về layout của cha.
+
+## Biến thể theo trục
+
+`mx-*` và `my-*` không phải rule riêng. Chúng áp một rule đã có lên một trục, khi chỉ một trục mang
+ngoại lệ đó.
+
+| Trục | Class | Nghĩa |
+| --- | --- | --- |
+| Inline | `mx-*` | Rule đã chọn chỉ áp cho cạnh đầu và cuối theo chiều ngang |
+| Block | `my-*` | Rule đã chọn chỉ áp cho cạnh trên và dưới |
+
+Trên cùng một phần tử, `m-*` và `mx-*` tranh nhau hai cạnh ngang chứ không cộng vào nhau. Margin
+trục block của hai phần tử kề nhau còn bị gộp lại, và đó là lý do thứ hai để gap của cha mới là chủ
+đáng tin của nhịp giữa các phần tử.
+
+## File này không quyết định
+
+Khoảng cách giữa các phần tử ngang hàng thuộc về [Gap](gap.md). Khoảng cách từ ranh giới tới nội
+dung thuộc về [Padding](padding.md). Giới hạn chiều rộng thuộc về [Measure](measure.md).

package/knowledge/ui/presentation/measure.md

@@ -0,0 +1,174 @@
+# Measure presentation
+
+This file answers one question: how much room does an application-owned content region take?
+
+Composition has already chosen the DOM tree and the Grammar objects. Measure resolves width and
+height constraints on regions the application owns. The internal dimensions of a card, input, control,
+or shell belong to Grammar.
+
+## Catalog
+
+Height has no closed value scale, and width has one only for caps (see Width scale), so the rule
+ID is an address over constraint kinds rather than a position on a ramp. Prefer the earliest rule that works: fluid before fitted, fitted
+before capped, capped before fixed.
+
+| Rule | Constraint | Decides |
+| --- | --- | --- |
+| MEASURE-1 | Page measure | Which packaged width a routed page adopts |
+| MEASURE-2 | Fluid width | A region follows the width it is given |
+| MEASURE-3 | Content width | A region grows only as far as its content |
+| MEASURE-4 | Capped width | A fluid region stops widening past a readable bound |
+| MEASURE-5 | Minimum height | A region reserves a floor and grows past it |
+| MEASURE-6 | Inherited height | A region fills a height its host already defines |
+| MEASURE-7 | Capped height | A region stops growing and hands scrolling to a boundary |
+
+A fixed width or height is absent from this catalog on purpose. A region whose size cannot respond to
+its content or its viewport is a layout decision made before presentation, and it is reported rather
+than written here.
+
+## Owner
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The region belongs to the application | The class |
+| A component name | Common already constrains this dimension | Nothing. Pass the prop |
+| `—` | Common exposes no public path | The class, recorded as a workaround |
+
+Every region that can receive long content also carries `min-w-0`. Without it a flex or grid child
+refuses to shrink below its content and pushes its neighbours out of the viewport. Common applies it
+throughout its own renderers; an application region that wraps text must do the same.
+
+## Width scale
+
+A capped width takes one step of this closed scale and nothing else; an arbitrary width such as
+`max-w-[720px]` is outside the scale and is removed by `frontend.presentation.resolve`. The prose cap
+`max-w-[65ch]` is the one character-based step, because line length follows the text. Owner ruling
+2026-09-03: the scale is fixed for every application, not derived per project.
+
+| Step | Class | Width |
+| --- | --- | --- |
+| W-sm | `max-w-sm` | 24rem |
+| W-md | `max-w-md` | 28rem |
+| W-lg | `max-w-lg` | 32rem |
+| W-xl | `max-w-xl` | 36rem |
+| W-2xl | `max-w-2xl` | 42rem |
+| W-3xl | `max-w-3xl` | 48rem |
+| W-4xl | `max-w-4xl` | 56rem |
+| W-5xl | `max-w-5xl` | 64rem |
+| W-6xl | `max-w-6xl` | 72rem |
+| W-7xl | `max-w-7xl` | 80rem |
+| W-prose | `max-w-[65ch]` | 65 characters |
+
+## Measure Common already owns
+
+Generated from `@grammar/core` claims by `scripts/generate-presentation-owned.mjs`; edit the component, not this table.
+
+| Component | Element or condition | Rule |
+| --- | --- | --- |
+| `HorizontalScrollRegion` | root | MEASURE-3 |
+| `NavigationFeatureNav` | root | MEASURE-2 |
+| `PageContainer` | root | MEASURE-1 |
+| `Progress` | root | MEASURE-2 |
+| `Rail` | body, height="fill" | MEASURE-6 |
+| `Sidebar` | root, presentation!="drawer" | MEASURE-6 |
+| `Sidebar` | root, presentation="drawer" | MEASURE-2 |
+| `TextAction` | root | MEASURE-3 |
+| `VerticalScrollRegion` | root, isScrollable | MEASURE-7 |
+| `WorkspaceShell` | layout | MEASURE-1 |
+
+## MEASURE-1 — Page measure
+
+A routed page adopts one packaged width instead of inventing its own.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A page of continuous prose that must stay readable | `PageContainer` | `<PageContainer measure="reading">` |
+| Case 2 | An ordinary product page of cards, tables, and controls | `PageContainer` | `<PageContainer>`, the product default |
+| Case 3 | A page whose content genuinely spans the viewport, such as a board or canvas | `PageContainer` | `<PageContainer measure="full">` |
+
+Not this rule: recreating the page width with a cap and a centring margin. That reproduces a
+component the page already has.
+
+## MEASURE-2 — Fluid width
+
+The region takes the width it is given and stays responsive.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A region that should follow the width supplied by its layout host | `App` | `<section className="w-full">` |
+| Case 2 | A control or field that must span its column | `App` | `w-full` on the app-owned wrapper, never inside the control |
+
+Not this rule: forcing a child past its parent's intended measure.
+
+## MEASURE-3 — Content width
+
+The region grows only as far as its content needs.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A compact region whose width should follow its own content | `App` | `<aside className="w-fit max-w-full">` |
+| Case 2 | Row content inside a horizontal scroll region | `HorizontalScrollRegion` | Compose the region; children already take `max-content` |
+
+Always pair `w-fit` with `max-w-full`. Without the cap, content longer than expected widens the
+region past its container and creates page-level horizontal scrolling.
+
+Not this rule: long prose, or a region that must fill its host.
+
+## MEASURE-4 — Capped width
+
+A fluid region stops widening once further width stops helping the reader.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A prose region whose line length needs a readable upper bound | `App` | `<article className="max-w-[65ch]">` |
+| Case 2 | A content region that loses its grouping past a known width | `App` | `<main className="w-full max-w-6xl">`, the cap one step of the Width scale |
+| Case 3 | A capped region whose content is narrower than the column it sits in, so the free space would otherwise gather on one side (a game table, a form, a media frame) | `App` | `<section className="w-full max-w-4xl mx-auto">`: the cap plus `mx-auto`, never a left-aligned cap |
+
+Character-based caps follow the text itself and belong to prose. Length-based caps belong to mixed
+content. Neither applies to tables, media, or code, which have their own intrinsic width.
+
+Not this rule: adding a cap because a screenshot looks sparse.
+
+## MEASURE-5 — Minimum height
+
+The region reserves a floor and still grows with its content.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A region needing a stable canvas before its content height is known | `App` | `<section className="min-h-[24rem]">` |
+| Case 2 | A region whose empty and populated states must not shift the page | `App` | The same floor on both states |
+
+Not this rule: reserving space for content that is absent by design. An empty state occupies its own
+region rather than a held-open gap.
+
+## MEASURE-6 — Inherited height
+
+The region fills a height its host already defines.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A region inside a host that supplies a definite height | `App` | `<section className="h-full">` inside a sized parent |
+| Case 2 | A rail that must run the full height of its shell | `Rail` | `height="fill"` on the rail |
+
+`h-full` resolves against a definite parent height and does nothing without one. In an indefinite
+chain it silently has no effect, which reads as a styling bug rather than a missing height.
+
+Not this rule: stretching ordinary document content.
+
+## MEASURE-7 — Capped height
+
+The region stops growing, and something inside it scrolls.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A list or panel that must not push the page beyond the viewport | `VerticalScrollRegion` | Compose the region; it owns the boundary |
+| Case 2 | An app-owned region with a bounded height and its own scroll | `App` | `max-h-*` together with the matching overflow rule |
+
+A capped height without a scroll owner clips content silently. The two decisions travel together.
+
+Not this rule: capping a region to hide content the reader still needs.
+
+## What this file does not decide
+
+Which boundary scrolls or clips is [Overflow](overflow.md). How text behaves inside the region is
+[Text flow](text-flow.md). Space around and inside the region is [Gap](gap.md) and [Padding](padding.md).

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

@@ -0,0 +1,178 @@
+# Measure presentation
+
+File này trả lời đúng một câu hỏi: một vùng nội dung do ứng dụng sở hữu thì chiếm bao nhiêu chỗ.
+
+Bước composition đã chọn xong cây DOM và các Grammar object. Measure giải quyết ràng buộc chiều rộng
+và chiều cao trên những vùng ứng dụng sở hữu. Kích thước bên trong một card, input, control hay shell
+đều thuộc về Grammar.
+
+## Danh mục
+
+Chiều cao không có thang giá trị đóng, còn chiều rộng chỉ có thang cho trần (xem Thang chiều rộng),
+nên số của rule ở đây là địa chỉ trên tập các kiểu ràng buộc chứ không phải vị trí trên một thang. Ưu tiên rule sớm nhất mà vẫn chạy được: co giãn
+trước, vừa nội dung sau, rồi mới tới chặn trần, cuối cùng mới tới cố định.
+
+| Rule | Ràng buộc | Quyết định |
+| --- | --- | --- |
+| MEASURE-1 | Khổ trang | Một trang được route lấy khổ đóng gói nào |
+| MEASURE-2 | Rộng co giãn | Vùng đi theo chiều rộng nó được cấp |
+| MEASURE-3 | Rộng theo nội dung | Vùng chỉ nở đúng bằng nội dung của nó |
+| MEASURE-4 | Chặn trần chiều rộng | Vùng co giãn ngừng nở khi qua ngưỡng đọc được |
+| MEASURE-5 | Chiều cao tối thiểu | Vùng giữ một mức sàn rồi vẫn cao thêm được |
+| MEASURE-6 | Chiều cao kế thừa | Vùng lấp đầy một chiều cao mà host đã định |
+| MEASURE-7 | Chặn trần chiều cao | Vùng ngừng cao và giao việc cuộn cho một ranh giới |
+
+Chiều rộng hay chiều cao cố định cố ý không có trong danh mục. Một vùng không phản ứng được với nội
+dung hay viewport là quyết định layout đã chốt trước bước presentation, và nó được báo cáo chứ không
+được viết ở đây.
+
+## Owner
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Vùng thuộc về ứng dụng | Viết class |
+| Tên component | Common đã ràng buộc kích thước này | Không viết gì, chỉ truyền prop |
+| `—` | Common chưa có đường dùng công khai | Viết class, ghi nhận là workaround |
+
+Mọi vùng có thể nhận nội dung dài đều phải mang thêm `min-w-0`. Thiếu nó, một phần tử con trong flex
+hay grid từ chối co nhỏ hơn nội dung của nó và đẩy các phần tử kề ra khỏi viewport. Common áp nó
+xuyên suốt các renderer của mình; một vùng của ứng dụng có bọc chữ thì phải làm y như vậy.
+
+## Thang chiều rộng
+
+Một chiều rộng bị chặn trần lấy đúng một bậc của thang đóng này, không gì khác; chiều rộng tuỳ ý như
+`max-w-[720px]` nằm ngoài thang và bị `frontend.presentation.resolve` gỡ bỏ. Trần cho văn xuôi `max-w-[65ch]`
+là bậc duy nhất tính theo ký tự, vì độ dài dòng đi theo con chữ. Chốt của owner ngày 2026-09-03: thang
+này cố định cho mọi ứng dụng, không suy ra theo từng dự án.
+
+| Bậc | Class | Chiều rộng |
+| --- | --- | --- |
+| W-sm | `max-w-sm` | 24rem |
+| W-md | `max-w-md` | 28rem |
+| W-lg | `max-w-lg` | 32rem |
+| W-xl | `max-w-xl` | 36rem |
+| W-2xl | `max-w-2xl` | 42rem |
+| W-3xl | `max-w-3xl` | 48rem |
+| W-4xl | `max-w-4xl` | 56rem |
+| W-5xl | `max-w-5xl` | 64rem |
+| W-6xl | `max-w-6xl` | 72rem |
+| W-7xl | `max-w-7xl` | 80rem |
+| W-prose | `max-w-[65ch]` | 65 ký tự |
+
+## Measure mà Common đã sở hữu
+
+Sinh từ claim của `@grammar/core` bằng `scripts/generate-presentation-owned.mjs`; muốn đổi thì sửa component, đừng sửa bảng này.
+
+| Component | Phần tử hoặc điều kiện | Rule |
+| --- | --- | --- |
+| `HorizontalScrollRegion` | root | MEASURE-3 |
+| `NavigationFeatureNav` | root | MEASURE-2 |
+| `PageContainer` | root | MEASURE-1 |
+| `Progress` | root | MEASURE-2 |
+| `Rail` | body, height="fill" | MEASURE-6 |
+| `Sidebar` | root, presentation!="drawer" | MEASURE-6 |
+| `Sidebar` | root, presentation="drawer" | MEASURE-2 |
+| `TextAction` | root | MEASURE-3 |
+| `VerticalScrollRegion` | root, isScrollable | MEASURE-7 |
+| `WorkspaceShell` | layout | MEASURE-1 |
+
+## MEASURE-1 — Khổ trang
+
+Một trang được route lấy đúng một khổ đóng gói sẵn thay vì tự chế khổ riêng.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Trang toàn văn xuôi liên tục, phải giữ cho đọc được | `PageContainer` | `<PageContainer measure="reading">` |
+| Case 2 | Trang sản phẩm thường gồm card, bảng và control | `PageContainer` | `<PageContainer>`, mặc định product |
+| Case 3 | Trang mà nội dung thật sự trải hết viewport, kiểu bảng kéo thả hay canvas | `PageContainer` | `<PageContainer measure="full">` |
+
+Không phải rule này: dựng lại khổ trang bằng một cái chặn trần cộng margin canh giữa. Như vậy là chế
+lại một component mà trang đã có sẵn.
+
+## MEASURE-2 — Rộng co giãn
+
+Vùng lấy đúng chiều rộng nó được cấp và giữ tính responsive.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một vùng cần đi theo chiều rộng do layout host cấp | `App` | `<section className="w-full">` |
+| Case 2 | Một control hoặc field phải trải hết cột của nó | `App` | `w-full` trên wrapper do app sở hữu, không bao giờ viết bên trong control |
+
+Không phải rule này: ép một phần tử con vượt quá khổ mà cha dự định.
+
+## MEASURE-3 — Rộng theo nội dung
+
+Vùng chỉ nở đúng bằng phần nội dung của nó cần.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một vùng gọn mà chiều rộng nên đi theo chính nội dung của nó | `App` | `<aside className="w-fit max-w-full">` |
+| Case 2 | Nội dung hàng bên trong một vùng cuộn ngang | `HorizontalScrollRegion` | Ghép region, các con đã tự lấy `max-content` |
+
+Luôn đi kèm `w-fit` với `max-w-full`. Không có cái chặn đó, nội dung dài hơn dự tính sẽ nong vùng
+vượt khỏi container và đẻ ra thanh cuộn ngang ở cấp trang.
+
+Không phải rule này: văn xuôi dài, hoặc một vùng phải lấp đầy host của nó.
+
+## MEASURE-4 — Chặn trần chiều rộng
+
+Vùng co giãn ngừng nở khi nở thêm không còn giúp người đọc.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Vùng văn xuôi mà độ dài dòng cần một ngưỡng trên để còn đọc được | `App` | `<article className="max-w-[65ch]">` |
+| Case 2 | Vùng nội dung mất tính gom nhóm khi vượt một chiều rộng đã biết | `App` | `<main className="w-full max-w-6xl">`, trần là một bậc của Thang chiều rộng |
+| Case 3 | Vùng bị chặn trần mà nội dung hẹp hơn cột chứa nó, khoảng trống sẽ dồn về một bên nếu để nguyên (sân bida, một form, một khung media) | `App` | `<section className="w-full max-w-4xl mx-auto">`: trần cộng `mx-auto`, không bao giờ chặn trần mà canh trái |
+
+Chặn theo số ký tự thì đi theo chính con chữ và thuộc về văn xuôi. Chặn theo độ dài thì thuộc về nội
+dung hỗn hợp. Cả hai đều không áp cho bảng, media hay code, vì những thứ đó có chiều rộng nội tại
+riêng.
+
+Không phải rule này: thêm chặn trần chỉ vì ảnh chụp nhìn trống.
+
+## MEASURE-5 — Chiều cao tối thiểu
+
+Vùng giữ một mức sàn mà vẫn cao thêm được theo nội dung.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một vùng cần khung ổn định trước khi biết chiều cao nội dung | `App` | `<section className="min-h-[24rem]">` |
+| Case 2 | Một vùng mà trạng thái rỗng và trạng thái có dữ liệu không được làm nhảy trang | `App` | Cùng một mức sàn cho cả hai trạng thái |
+
+Không phải rule này: chừa chỗ cho nội dung vốn dĩ không tồn tại. Trạng thái rỗng chiếm vùng của chính
+nó chứ không phải một khoảng trống giữ sẵn.
+
+## MEASURE-6 — Chiều cao kế thừa
+
+Vùng lấp đầy một chiều cao mà host đã định sẵn.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một vùng nằm trong host đã cấp chiều cao xác định | `App` | `<section className="h-full">` trong một cha đã có kích thước |
+| Case 2 | Một rail phải chạy hết chiều cao shell của nó | `Rail` | `height="fill"` trên rail |
+
+`h-full` quy chiếu theo chiều cao xác định của cha và không làm gì nếu cha không có. Trong một chuỗi
+không xác định, nó im lặng không có tác dụng, và điều đó đọc lên như lỗi style chứ không phải như
+thiếu chiều cao.
+
+Không phải rule này: kéo giãn nội dung tài liệu thông thường.
+
+## MEASURE-7 — Chặn trần chiều cao
+
+Vùng ngừng cao thêm, và một thứ gì đó bên trong nó cuộn.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một danh sách hoặc panel không được đẩy trang vượt quá viewport | `VerticalScrollRegion` | Ghép region, nó sở hữu ranh giới đó |
+| Case 2 | Một vùng do app sở hữu, có chiều cao giới hạn và có cuộn riêng | `App` | `max-h-*` đi cùng rule overflow tương ứng |
+
+Chặn trần chiều cao mà không có chủ cuộn thì cắt cụt nội dung trong im lặng. Hai quyết định đó đi
+liền nhau.
+
+Không phải rule này: chặn một vùng để giấu nội dung mà người đọc vẫn cần.
+
+## File này không quyết định
+
+Ranh giới nào cuộn hay cắt thuộc về [Overflow](overflow.md). Chữ hành xử ra sao bên trong vùng thuộc
+về [Text flow](text-flow.md). Khoảng cách quanh và bên trong vùng thuộc về [Gap](gap.md) và
+[Padding](padding.md).

package/knowledge/ui/presentation/overflow.md

@@ -0,0 +1,142 @@
+# Overflow presentation
+
+This file answers one question: when content exceeds its region, which boundary owns that, and what
+does it do?
+
+Composition has chosen the tree and [Measure](measure.md) has bounded the region. Overflow resolves
+what happens at the edge of a boundary the application owns. Clipping and scrolling inside a card,
+rail, table frame, or shell belong to Grammar.
+
+## Catalog
+
+| Rule | Boundary behaviour | Content beyond the edge |
+| --- | --- | --- |
+| OVERFLOW-1 | Visible | Escapes the boundary and remains readable |
+| OVERFLOW-2 | Clipped | Is cut and unreachable |
+| OVERFLOW-3 | Scrolls on one axis | Is reachable by scrolling that axis |
+| OVERFLOW-4 | Scrolls when needed | Is reachable only when it exists |
+| OVERFLOW-5 | Contained | Scrolls without handing the gesture to the page |
+
+Exactly one boundary owns each axis. Two nested scrollers on the same axis trap the reader between
+them, and neither reaches the end reliably.
+
+## Owner
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The boundary belongs to the application | The class |
+| A component name | Common already owns this boundary | Nothing. Compose it |
+| `—` | Common exposes no public path | The class, recorded as a workaround |
+
+A scroll boundary is never written alone. It travels with a bound from [Measure](measure.md), because
+a region with no height cap never overflows and its scroll class does nothing.
+
+## Overflow Common already owns
+
+Generated from `@grammar/core` claims by `scripts/generate-presentation-owned.mjs`; edit the component, not this table.
+
+| Component | Element or condition | Rule |
+| --- | --- | --- |
+| `ChatWorkspace` | conversation | OVERFLOW-4 |
+| `ChatWorkspace` | conversation | OVERFLOW-5 |
+| `ChatWorkspace` | drawer body, hasRail, isCompactRail | OVERFLOW-2 |
+| `ChatWorkspace` | overlay rail, hasRail, isCompactRail | OVERFLOW-4 |
+| `ChatWorkspace` | overlay rail, hasRail, isCompactRail | OVERFLOW-5 |
+| `ChatWorkspace` | overlay rail, hasRail, not isCompactRail | OVERFLOW-4 |
+| `ChatWorkspace` | overlay rail, hasRail, not isCompactRail | OVERFLOW-5 |
+| `FencedCodeBlock` | root | OVERFLOW-4 |
+| `HorizontalScrollRegion` | root | OVERFLOW-3 |
+| `HorizontalScrollRegion` | root | OVERFLOW-5 |
+| `IconTile` | root | OVERFLOW-2 |
+| `MarkdownTableFrame` | root | OVERFLOW-4 |
+| `MediaFrame` | root | OVERFLOW-2 |
+| `OtpInput` | root | OVERFLOW-3 |
+| `OtpInput` | root | OVERFLOW-5 |
+| `Rail` | body, height!="fill" | OVERFLOW-3 |
+| `Sidebar` | root | OVERFLOW-2 |
+| `SurfaceAccordionCard` | accordion shell | OVERFLOW-2 |
+| `SurfaceAccordionCard` | accordion shell, not bounded | OVERFLOW-1 |
+| `SurfaceCard` | card content | OVERFLOW-2 |
+| `SurfaceCard` | card content, frame="frameless" | OVERFLOW-1 |
+| `SurfaceListCard` | root | OVERFLOW-2 |
+| `Tabs` | scroll | OVERFLOW-4 |
+| `VerticalScrollRegion` | root, isScrollable | OVERFLOW-3 |
+| `WorkspaceShell` | floating layer, hasFloatingLayer | OVERFLOW-4 |
+
+## OVERFLOW-1 — Visible
+
+The boundary does not clip, because something must be allowed to cross it.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A region whose child carries a focus ring, shadow, or badge that sits outside the box | `App` | No class. Visible is the default |
+| Case 2 | A surface that must not clip its own highlight | `SurfaceCard` | The frameless variant already stays visible |
+
+Not this rule: leaving a bounded region visible to avoid deciding. Content that escapes silently
+overlaps whatever follows it.
+
+## OVERFLOW-2 — Clipped
+
+Content is cut at the boundary and cannot be reached.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A rounded region whose children must stay inside the radius | `SurfaceCard` | Compose the card; it already clips |
+| Case 2 | A media viewport that crops its image to a fixed frame | `MediaFrame` | Compose the frame; it already clips |
+| Case 3 | An app-owned decorative region whose overflow carries no information | `App` | `overflow-hidden` |
+
+Clipping content the reader needs is silent data loss. It looks correct in a screenshot at one width
+and fails at another, which is why it is the hardest overflow defect to find.
+
+Not this rule: text that does not fit. That is [Text flow](text-flow.md), and it truncates visibly
+rather than disappearing.
+
+## OVERFLOW-3 — Scrolls on one axis
+
+The boundary always scrolls one axis, because its content is expected to exceed it.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A row of items intentionally wider than the viewport | `HorizontalScrollRegion` | Compose the region |
+| Case 2 | A bounded panel or list whose content grows | `VerticalScrollRegion` | Compose the region |
+| Case 3 | A rail body that scrolls while its shell stays put | `Rail` | Compose the rail |
+
+The other axis stays clipped or visible on purpose. A region that scrolls both axes hides content in
+a direction the reader has no reason to look.
+
+Not this rule: a region whose content usually fits. Use OVERFLOW-4 so the bar appears only when it
+means something.
+
+## OVERFLOW-4 — Scrolls when needed
+
+The boundary scrolls only when content actually exceeds it.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A wide table inside a narrower column | `MarkdownTableFrame` | Compose the frame |
+| Case 2 | Long code lines that must not wrap | `FencedCodeBlock` | Compose the block |
+| Case 3 | A tab strip that exceeds its width only in some languages | `Tabs` | Compose the tabs |
+| Case 4 | An app-owned bounded region whose content sometimes exceeds it | `App` | `overflow-auto` with the matching height cap |
+
+Not this rule: an always-visible bar on a region that usually fits, which reads as a defect the first
+time a reader sees it empty.
+
+## OVERFLOW-5 — Contained
+
+Scrolling stops at this boundary instead of continuing into the page behind it.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A scrolling panel, drawer, or overlay above page content | `—` | `overscroll-contain` with the scroll rule |
+| Case 2 | A horizontal row inside a vertically scrolling page | `HorizontalScrollRegion` | Compose the region; it already contains the inline axis |
+
+Without containment, reaching the end of the inner region hands the gesture to the page and the
+reader loses their place. On a touch device the effect is worse, because the page moves under a
+finger that was scrolling something else.
+
+Not this rule: containment on the page's own scroller, which would trap the reader.
+
+## What this file does not decide
+
+How large the region is, and whether it has a height cap at all, is [Measure](measure.md). What text
+does when it does not fit is [Text flow](text-flow.md).