@starci/skills 1.1.0

package/knowledge/ui/presentation/text-flow.md

@@ -0,0 +1,123 @@
+# Text flow presentation
+
+This file answers one question: how does text behave inside a region whose size is already decided?
+
+Composition has chosen the tree, [Font](font.md) has set the rank, and [Measure](measure.md) has set
+the room. Text flow resolves alignment, wrapping, and what happens when the words do not fit.
+
+The default is the correct answer far more often than any rule here. Text that starts at the reading
+edge and wraps naturally needs no class at all.
+
+## Catalog
+
+| Rule | Decides | Default |
+| --- | --- | --- |
+| FLOW-1 | Alignment along the inline axis | Start |
+| FLOW-2 | Whether a line may break | Wrapping |
+| FLOW-3 | Breaking inside an unbroken string | Allowed on overflow |
+| FLOW-4 | Truncating one line | Off |
+| FLOW-5 | Clamping several lines | Off |
+
+Truncation removes information. FLOW-4 and FLOW-5 are valid only when the full text remains reachable
+somewhere else, and never for a value the reader must act on.
+
+## Owner
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The text region belongs to the application | The class |
+| A component name | Common already resolves this behaviour | Nothing. Compose it |
+| `—` | Common exposes no public path | The class, recorded as a workaround |
+
+Every wrapping region also needs `min-w-0` from [Measure](measure.md). Truncation and clamping fail
+silently without it, because the region never becomes narrower than its longest word.
+
+## Text flow 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 |
+| --- | --- | --- |
+| `MediaFrame` | caption, caption!=undefined | FLOW-3 |
+| `SectionHeader` | title | FLOW-3 |
+| `Sidebar` | item label, not collapsed | FLOW-4 |
+| `Subnav` | title | FLOW-4 |
+| `Tabs` | hero tabs list container wrapper | FLOW-2 |
+| `Tooltip` | content | FLOW-2 |
+
+## FLOW-1 — Alignment
+
+Text starts at the reading edge unless the content itself is a quantity being compared.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Any prose, label, heading, or explanation | `App` | No class. Start alignment is the default |
+| Case 2 | A numeric column whose values are compared down the column | `App` | `text-end` on the cell, applied to the whole column |
+| Case 3 | A single short line centred inside a deliberately symmetric region | `App` | `text-center` on the app-owned region only |
+
+Not this rule: centring paragraphs. A centred block has a ragged start edge, and every line costs the
+reader a search for where it begins. Justified text is never used, because it opens uneven rivers of
+space at the widths this system supports.
+
+## FLOW-2 — Wrapping
+
+A line wraps by default. Preventing that is a promise the content is short.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Any content whose length is not fixed | `App` | No class. Wrapping is the default |
+| Case 2 | A control label, badge, or tab that must not break mid-phrase | The component | Compose it; Common already keeps it on one line |
+| Case 3 | Code that must keep its own line breaks | `FencedCodeBlock` | Compose the block; it scrolls instead of wrapping |
+
+Not this rule: `whitespace-nowrap` on translated or user-supplied text. A phrase that fits in one
+language overflows in another, and the overflow appears only after release.
+
+## FLOW-3 — Breaking inside a word
+
+A single unbroken string longer than its region breaks rather than escaping it.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Content that can contain a URL, token, identifier, or pasted string | `App` | `break-words` on the app-owned region |
+| Case 2 | Section titles, captions, and article prose | The component | Compose it; Common already breaks these |
+
+This is the rule that prevents page-level horizontal scrolling. One email address in a narrow column
+widens every ancestor without it.
+
+Not this rule: breaking short labels, which produces a single stranded character on the second line.
+
+## FLOW-4 — Truncating one line
+
+One line is cut with an ellipsis because its region has a fixed inline size and the full value is
+available elsewhere.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A title in a fixed-width strip whose full text is on the destination page | `Subnav` | Compose it; Common already truncates |
+| Case 2 | An app-owned row label whose full value is reachable by opening the row | `App` | `truncate` with `min-w-0` on the same element |
+
+The visible text must remain the accessible name in full. A truncated label that also truncates its
+accessible name removes the value from assistive output entirely.
+
+Not this rule: a price, status, error, deadline, or any value the reader acts on. Give the region
+more room instead.
+
+## FLOW-5 — Clamping several lines
+
+A block is cut after a fixed number of lines, and the reader can open the full text.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A card description in a grid whose cards must stay the same height | `—` | `line-clamp-2` with an affordance that reveals the rest |
+| Case 2 | A preview whose full body is the destination of the row | `—` | Same, with the row as the affordance |
+
+A clamp without a way to read the rest is content deletion. The affordance is part of the rule, not a
+later addition. Common exposes no clamp prop, so both cases stay recorded workarounds.
+
+Not this rule: clamping to hide a layout problem. If two cards differ in height because their content
+differs, that is the content, not a defect.
+
+## What this file does not decide
+
+The size and weight of the text is [Font](font.md). Its colour is [Tone](tone.md). How much room the
+region gets is [Measure](measure.md). Which boundary scrolls is [Overflow](overflow.md).

package/knowledge/ui/presentation/text-flow.vi.md

@@ -0,0 +1,123 @@
+# Text flow presentation
+
+File này trả lời đúng một câu hỏi: chữ hành xử ra sao bên trong một vùng đã chốt kích thước.
+
+Composition đã chọn cây DOM, [Font](font.md) đã đặt hạng, và [Measure](measure.md) đã đặt chỗ. Text
+flow giải quyết canh lề, xuống dòng, và chuyện gì xảy ra khi chữ không vừa.
+
+Giá trị mặc định mới là đáp án đúng, thường xuyên hơn bất kỳ rule nào ở đây. Chữ bắt đầu từ mép đọc
+và xuống dòng tự nhiên thì không cần class nào cả.
+
+## Danh mục
+
+| Rule | Quyết định | Mặc định |
+| --- | --- | --- |
+| FLOW-1 | Canh lề theo trục inline | Đầu dòng |
+| FLOW-2 | Một dòng có được phép ngắt không | Có xuống dòng |
+| FLOW-3 | Ngắt bên trong một chuỗi liền không khoảng trắng | Cho phép khi tràn |
+| FLOW-4 | Cắt cụt một dòng | Tắt |
+| FLOW-5 | Chặn số dòng | Tắt |
+
+Cắt cụt là gỡ bỏ thông tin. FLOW-4 và FLOW-5 chỉ hợp lệ khi toàn văn còn đọc được ở chỗ khác, và
+không bao giờ dùng cho một giá trị mà người đọc phải hành động theo.
+
+## Owner
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Vùng chữ thuộc về ứng dụng | Viết class |
+| Tên component | Common đã xử lý hành vi này | Không viết gì, chỉ ghép component |
+| `—` | Common chưa có đường dùng công khai | Viết class, ghi nhận là workaround |
+
+Mọi vùng có xuống dòng đều cần thêm `min-w-0` từ [Measure](measure.md). Thiếu nó thì cắt cụt và chặn
+dòng hỏng trong im lặng, vì vùng không bao giờ hẹp hơn từ dài nhất của nó.
+
+## Text flow 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 |
+| --- | --- | --- |
+| `MediaFrame` | caption, caption!=undefined | FLOW-3 |
+| `SectionHeader` | title | FLOW-3 |
+| `Sidebar` | item label, not collapsed | FLOW-4 |
+| `Subnav` | title | FLOW-4 |
+| `Tabs` | hero tabs list container wrapper | FLOW-2 |
+| `Tooltip` | content | FLOW-2 |
+
+## FLOW-1 — Canh lề
+
+Chữ bắt đầu từ mép đọc, trừ khi bản thân nội dung là một con số đang được đem so sánh.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Mọi văn xuôi, nhãn, tiêu đề hay lời giải thích | `App` | Không viết class. Canh đầu dòng là mặc định |
+| Case 2 | Một cột số mà các giá trị được so sánh dọc theo cột | `App` | `text-end` trên ô, áp cho cả cột |
+| Case 3 | Một dòng ngắn duy nhất canh giữa trong một vùng cố ý đối xứng | `App` | `text-center` chỉ trên vùng do app sở hữu |
+
+Không phải rule này: canh giữa cả đoạn văn. Khối canh giữa có mép đầu răng cưa, và mỗi dòng bắt người
+đọc phải đi tìm chỗ bắt đầu. Không bao giờ dùng canh đều hai bên, vì ở những khổ mà hệ này hỗ trợ nó
+mở ra các dòng sông khoảng trắng lệch nhau.
+
+## FLOW-2 — Xuống dòng
+
+Một dòng mặc định là có xuống dòng. Chặn nó lại là một lời hứa rằng nội dung ngắn.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Mọi nội dung mà độ dài không cố định | `App` | Không viết class. Xuống dòng là mặc định |
+| Case 2 | Nhãn control, badge hay tab không được ngắt giữa cụm từ | Chính component đó | Ghép nó, Common đã giữ trên một dòng |
+| Case 3 | Code phải giữ đúng các dấu xuống dòng của chính nó | `FencedCodeBlock` | Ghép khối, nó cuộn thay vì xuống dòng |
+
+Không phải rule này: `whitespace-nowrap` trên chữ đã dịch hoặc chữ do người dùng nhập. Một cụm vừa
+khít ở ngôn ngữ này sẽ tràn ở ngôn ngữ khác, và cái tràn đó chỉ lộ ra sau khi phát hành.
+
+## FLOW-3 — Ngắt bên trong một từ
+
+Một chuỗi liền không khoảng trắng, dài hơn vùng chứa, thì ngắt ra chứ không thoát ra ngoài.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Nội dung có thể chứa URL, token, mã định danh hay chuỗi dán vào | `App` | `break-words` trên vùng do app sở hữu |
+| Case 2 | Tiêu đề section, chú thích ảnh và văn xuôi article | Chính component đó | Ghép nó, Common đã ngắt sẵn |
+
+Đây là rule chặn thanh cuộn ngang ở cấp trang. Chỉ một địa chỉ email trong một cột hẹp là nong rộng
+mọi phần tử tổ tiên nếu thiếu nó.
+
+Không phải rule này: ngắt các nhãn ngắn, vì như vậy đẻ ra một ký tự lạc lõng ở dòng thứ hai.
+
+## FLOW-4 — Cắt cụt một dòng
+
+Một dòng bị cắt kèm dấu ba chấm vì vùng của nó có chiều rộng cố định và giá trị đầy đủ có ở chỗ khác.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Tiêu đề trong một dải rộng cố định, toàn văn nằm ở trang đích | `Subnav` | Ghép nó, Common đã cắt cụt sẵn |
+| Case 2 | Nhãn một hàng do app sở hữu, giá trị đầy đủ mở ra được bằng cách mở hàng đó | `App` | `truncate` cùng `min-w-0` trên chính phần tử đó |
+
+Chữ nhìn thấy vẫn phải giữ nguyên accessible name đầy đủ. Một nhãn cắt cụt mà cắt luôn accessible
+name là xóa hẳn giá trị đó khỏi đầu ra cho trình đọc màn hình.
+
+Không phải rule này: giá tiền, trạng thái, lỗi, hạn chót, hay bất kỳ giá trị nào người đọc phải hành
+động theo. Cho vùng đó thêm chỗ thay vì cắt.
+
+## FLOW-5 — Chặn số dòng
+
+Một khối bị cắt sau một số dòng cố định, và người đọc mở ra xem toàn văn được.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Mô tả của card trong một lưới mà các card phải bằng chiều cao | `—` | `line-clamp-2` kèm một cách để mở phần còn lại |
+| Case 2 | Một đoạn xem trước mà toàn văn chính là đích đến của hàng đó | `—` | Cũng vậy, chính hàng đó là cách mở |
+
+Chặn dòng mà không có đường đọc tiếp là xóa nội dung. Cái đường mở đó là một phần của rule, không
+phải thứ thêm vào sau. Common chưa có prop chặn dòng nào, nên cả hai case đều là workaround có ghi
+nhận.
+
+Không phải rule này: chặn dòng để giấu một lỗi layout. Nếu hai card lệch chiều cao vì nội dung khác
+nhau, thì đó là nội dung, không phải lỗi.
+
+## File này không quyết định
+
+Cỡ chữ và độ đậm thuộc về [Font](font.md). Màu chữ thuộc về [Tone](tone.md). Vùng được bao nhiêu chỗ
+thuộc về [Measure](measure.md). Ranh giới nào cuộn thuộc về [Overflow](overflow.md).

package/knowledge/ui/presentation/tone.md

@@ -0,0 +1,114 @@
+# Tone presentation
+
+This file answers one question: given a line of copy whose rank is already decided, which public tone
+prop expresses that rank?
+
+Tone is a semantic choice, not a colour choice. The application selects how much attention a line
+deserves; Grammar resolves that to a token. The application never writes a text colour class and
+never overrides colour inside another Grammar component.
+
+## Scale
+
+The public tone set is closed and ordered by how much attention each level claims.
+
+| Rule | Prop | Rendered token | Claims |
+| --- | --- | --- | --- |
+| TONE-1 | `tone="default"` | `text-foreground` | Ordinary reading attention |
+| TONE-2 | `tone="muted"` | `text-muted` | Deliberately less than its neighbour |
+| TONE-3 | `tone="accent"` | `text-accent-soft-foreground` | Scarce, one short span at a time |
+
+`Text size="xs"` resolves to muted regardless of the tone requested, because the smallest size is
+supporting information by definition. `Heading level={4}` carries the same muted treatment. Asking
+for another tone at that size does not raise it.
+
+## Owner
+
+Tone belongs to Grammar. The owner cell names which component resolves the token.
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| A component name | `Text` resolves this tone | The prop only |
+| `—` | The meaning has no public tone | Nothing. Report the gap |
+
+There is no `App` owner in this file. A `text-*` colour class written by the application is
+`APP_OVERRIDE`, and a raw hex or palette value is rejected even when it matches the token.
+
+Status colour is not tone. Success, warning, danger, and information are semantic states owned by the
+components that carry them, and they are never expressed by choosing a text colour.
+
+## Tone 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` | drawer close, hasRail, isCompactRail | TONE-1 |
+| `ChatWorkspace` | rail trigger, hasRail, isCompactRail | TONE-1 |
+| `Heading` | root, scale!="display", level=4 | TONE-2 |
+| `IconTile` | root, not (isSkeleton || showsArtwork), tone="neutral" | TONE-2 |
+| `Input` | button, not (!isSecret || toggleLabel === undefined) | TONE-2 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | TONE-2 |
+| `Sidebar` | list box item | TONE-1 |
+| `SurfaceAccordionCard` | accordion body | TONE-1 |
+| `SurfaceListCard` | fact, not (label === undefined || labelHidden), fact!=undefined | TONE-2 |
+| `Text` | root, not isSkeleton, resolvedTone="accent" | TONE-3 |
+| `Text` | root, not isSkeleton, resolvedTone="default" | TONE-1 |
+| `Text` | root, not isSkeleton, resolvedTone="muted" | TONE-2 |
+| `TextAction` | root, appearance="disclosure" | TONE-3 |
+| `TextAction` | root, appearance="muted" | TONE-2 |
+| `TextAction` | root, appearance="plain" | TONE-1 |
+| `TextAction` | root, appearance="route", isCurrent | TONE-3 |
+| `TextAction` | root, appearance="route", not isCurrent | TONE-2 |
+| `TextAction` | root, appearance="section", isCurrent | TONE-3 |
+| `TextAction` | root, appearance="section", not isCurrent | TONE-1 |
+| `TextAction` | root, appearance="tab", not isCurrent | TONE-2 |
+
+## TONE-1 — `tone="default"`
+
+The line reads at ordinary attention. This is the resolved tone when none is given, except at the
+smallest size.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Copy or a fact the application ranked as normal reading content | `Text` | `<Text tone="default">Enrollment is active.</Text>` |
+| Case 2 | The body of a paired title and explanation where both must be read | `Text` | Both lines stay default; weight separates them |
+
+Not this rule: making lower-rank metadata compete with the content beside it. Use TONE-2.
+
+## TONE-2 — `tone="muted"`
+
+The line recedes on purpose, because something next to it carries the meaning.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A qualifier, unit, or timestamp attached to a fact stated nearby | `Text` | `<Text tone="muted">Taxes are calculated at checkout.</Text>` |
+| Case 2 | The description under a title, where the title carries the identity | `Text` | `<Text size="sm" tone="muted">Ready for junior roles</Text>` |
+| Case 3 | Any line at the smallest size | `Text` | `size="xs"` already resolves to muted |
+
+Not this rule: the only sentence explaining an important fact, or hiding copy that is simply too
+long. Muting an explanation nobody else states removes it from the page in practice.
+
+## TONE-3 — `tone="accent"`
+
+One short span stands out because its meaning is already exceptional in context.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A single short label whose emphasis the application has already decided | `Text` | `<Text tone="accent" weight="semibold">Recommended</Text>` |
+
+Not this rule: whole paragraphs, repeated peers, or decoration. Accent repeated across siblings stops
+marking anything. Accent also never carries meaning alone, because colour is not readable by every
+reader.
+
+## Contrast
+
+Tone tokens are defined against the surface they sit on. A tone chosen on one surface and rendered on
+another is a contrast finding, not a preference, and it is measured against the composed background
+rather than the intended one.
+
+The application changes the surface, never the token, when contrast fails.
+
+## What this file does not decide
+
+How large or heavy the line is set is [Font](font.md). Which surface it sits on, and the semantic
+colour of that surface, are outside presentation entirely.

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

@@ -0,0 +1,113 @@
+# Tone presentation
+
+File này trả lời đúng một câu hỏi: một dòng chữ đã xếp hạng xong thì diễn đạt hạng đó bằng prop tone
+công khai nào.
+
+Tone là lựa chọn ngữ nghĩa chứ không phải lựa chọn màu. Ứng dụng chọn dòng đó đáng được chú ý bao
+nhiêu, Grammar quy nó về một token. Ứng dụng không bao giờ viết class màu chữ và không ghi đè màu
+bên trong một Grammar component khác.
+
+## Thang giá trị
+
+Tập tone công khai là tập đóng, xếp theo mức chú ý mà mỗi bậc đòi hỏi.
+
+| Rule | Prop | Token render ra | Đòi hỏi |
+| --- | --- | --- | --- |
+| TONE-1 | `tone="default"` | `text-foreground` | Mức chú ý đọc thông thường |
+| TONE-2 | `tone="muted"` | `text-muted` | Cố ý thấp hơn dòng bên cạnh |
+| TONE-3 | `tone="accent"` | `text-accent-soft-foreground` | Khan hiếm, mỗi lần một đoạn ngắn |
+
+`Text size="xs"` quy về muted bất kể tone được yêu cầu là gì, vì cỡ nhỏ nhất đã là thông tin phụ theo
+định nghĩa. `Heading level={4}` mang đúng cách xử lý muted đó. Xin một tone khác ở cỡ này cũng không
+nâng nó lên được.
+
+## Owner
+
+Tone thuộc về Grammar. Ô owner gọi tên component nào quy ra token.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| Tên component | `Text` quy ra tone này | Chỉ truyền prop |
+| `—` | Ý nghĩa này chưa có tone công khai | Không viết gì, báo là thiếu |
+
+File này không có owner `App`. Một class màu `text-*` do ứng dụng viết là `APP_OVERRIDE`, và một mã
+hex hay giá trị palette thô thì bị từ chối kể cả khi nó trùng token.
+
+Màu trạng thái không phải tone. Thành công, cảnh báo, nguy hiểm và thông tin là những trạng thái ngữ
+nghĩa do chính component mang chúng sở hữu, và không bao giờ được diễn đạt bằng cách chọn màu chữ.
+
+## Tone 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 |
+| --- | --- | --- |
+| `ChatWorkspace` | drawer close, hasRail, isCompactRail | TONE-1 |
+| `ChatWorkspace` | rail trigger, hasRail, isCompactRail | TONE-1 |
+| `Heading` | root, scale!="display", level=4 | TONE-2 |
+| `IconTile` | root, not (isSkeleton || showsArtwork), tone="neutral" | TONE-2 |
+| `Input` | button, not (!isSecret || toggleLabel === undefined) | TONE-2 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | TONE-2 |
+| `Sidebar` | list box item | TONE-1 |
+| `SurfaceAccordionCard` | accordion body | TONE-1 |
+| `SurfaceListCard` | fact, not (label === undefined || labelHidden), fact!=undefined | TONE-2 |
+| `Text` | root, not isSkeleton, resolvedTone="accent" | TONE-3 |
+| `Text` | root, not isSkeleton, resolvedTone="default" | TONE-1 |
+| `Text` | root, not isSkeleton, resolvedTone="muted" | TONE-2 |
+| `TextAction` | root, appearance="disclosure" | TONE-3 |
+| `TextAction` | root, appearance="muted" | TONE-2 |
+| `TextAction` | root, appearance="plain" | TONE-1 |
+| `TextAction` | root, appearance="route", isCurrent | TONE-3 |
+| `TextAction` | root, appearance="route", not isCurrent | TONE-2 |
+| `TextAction` | root, appearance="section", isCurrent | TONE-3 |
+| `TextAction` | root, appearance="section", not isCurrent | TONE-1 |
+| `TextAction` | root, appearance="tab", not isCurrent | TONE-2 |
+
+## TONE-1 — `tone="default"`
+
+Dòng chữ đọc ở mức chú ý thông thường. Đây là tone mặc định khi không truyền gì, trừ ở cỡ nhỏ nhất.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Copy hoặc dữ kiện mà ứng dụng xếp là nội dung đọc thường | `Text` | `<Text tone="default">Enrollment is active.</Text>` |
+| Case 2 | Phần thân của một cặp tiêu đề và giải thích mà cả hai đều phải đọc | `Text` | Cả hai dòng giữ default, độ đậm mới là thứ tách chúng |
+
+Không phải rule này: để metadata hạng thấp cạnh tranh với nội dung bên cạnh. Dùng TONE-2.
+
+## TONE-2 — `tone="muted"`
+
+Dòng chữ lùi lại có chủ ý, vì thứ nằm cạnh nó mới mang nghĩa chính.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một dòng bổ nghĩa, đơn vị, hay mốc thời gian gắn với một dữ kiện nêu ngay gần đó | `Text` | `<Text tone="muted">Taxes are calculated at checkout.</Text>` |
+| Case 2 | Phần mô tả dưới một tiêu đề, mà tiêu đề mới mang danh tính | `Text` | `<Text size="sm" tone="muted">Ready for junior roles</Text>` |
+| Case 3 | Bất kỳ dòng nào ở cỡ nhỏ nhất | `Text` | `size="xs"` đã tự quy về muted |
+
+Không phải rule này: câu duy nhất giải thích một dữ kiện quan trọng, hoặc để giấu bớt phần copy chỉ
+vì nó dài. Làm mờ một lời giải thích mà không ai khác nói lại, trên thực tế là gỡ nó khỏi trang.
+
+## TONE-3 — `tone="accent"`
+
+Một đoạn ngắn nổi lên vì ý nghĩa của nó vốn đã đặc biệt trong ngữ cảnh đó.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một nhãn ngắn duy nhất mà ứng dụng đã quyết định là cần nhấn | `Text` | `<Text tone="accent" weight="semibold">Recommended</Text>` |
+
+Không phải rule này: cả đoạn văn, các phần tử ngang hàng lặp lại, hay trang trí. Accent lặp trên
+nhiều phần tử ngang hàng thì thôi đánh dấu được gì. Accent cũng không bao giờ mang nghĩa một mình,
+vì không phải người đọc nào cũng đọc được màu.
+
+## Tương phản
+
+Token tone được định nghĩa so với chính surface mà nó nằm lên. Một tone chọn trên surface này rồi
+render trên surface khác là một phát hiện về tương phản chứ không phải chuyện thẩm mỹ, và nó được đo
+so với nền thật sự đang chồng lên chứ không phải nền dự định.
+
+Khi tương phản không đạt thì ứng dụng đổi surface, không bao giờ đổi token.
+
+## File này không quyết định
+
+Dòng chữ được đặt to hay đậm cỡ nào thuộc về [Font](font.md). Nó nằm trên surface nào, và màu ngữ
+nghĩa của surface đó, thì nằm hoàn toàn ngoài phạm vi presentation.

package/knowledge/ui/proof/INDEX.md

@@ -0,0 +1,55 @@
+# UI proof
+
+Proof is the decision layer that only exists after the page has rendered:
+
+```text
+business
+-> composition decides regions, rank, actions, states and emphasis
+-> presentation resolves CSS values on app-owned boundaries
+-> rendered UI  <- proof observes here
+```
+
+Every rule in this folder is consumed by the audit operator. That operator has no access to intent,
+only to output: the accessibility tree that was computed, the element that actually holds focus, the
+frame where the animation stopped, and the claim the page ended up making. These topics belong
+together because none of them can be established by reading source. A `:focus-visible` rule does not
+prove a visible indicator, a `label` prop does not prove a computed name, a `motion` attribute does
+not prove a transition, and an approved copy deck does not prove what the rendered page asserts.
+Each rule therefore states the observation that would falsify it, so a passing verdict always names
+something that was looked at.
+
+## Catalog
+
+| Knowledge | What it decides | Rules |
+| --- | --- | --- |
+| [Accessibility](accessibility.md) | Whether names, relationships, targets and contrast reach every reader | A11Y-1 to A11Y-4 |
+| [Contrast](contrast.md) | Whether distinctions and text survive measurement in every theme and state | COLOR-3, COLOR-5 |
+| [Focus](focus.md) | Where focus is visible, how far it travels, and where it returns | FOCUS-1 to FOCUS-5 |
+| [Motion](motion.md) | Whether meaning survives with the movement stopped, reduced or interrupted | MOTION-1 to MOTION-4 |
+| [Render truth](render-truth.md) | Whether every rendered claim traces back to real authority | TRUTH-1 to TRUTH-4 |
+
+## Rule shape
+
+`A11Y-1`, `FOCUS-5`, and the other `PREFIX-n` names are stable ordinal addresses within their topic.
+The number is not a severity or a conformance level. A topic may publish a non-contiguous series:
+`contrast.md` publishes only `COLOR-3` and `COLOR-5`, because the other numbers of that prefix were
+retired with the topic they came from and are never reused.
+
+Every rule carries its heading, one line naming what the rule governs, and one table:
+
+| Case | When | Observe |
+| --- | --- | --- |
+| Case 1 | The concrete rendered situation that reaches this rule. | The exact runtime evidence, and what seeing it would falsify. |
+
+The `Observe` cell names a thing that can be captured from the running page — a computed name, an
+active element, a measured rectangle, a computed duration, a traced result — and says what a
+contrary observation would disprove. It never restates an intention.
+
+A case that belongs to a neighbouring rule is not a table row. It goes on one line after the table,
+as `Not this rule: <condition> is PREFIX-n`. Each file closes with a
+`## What this file does not decide` section linking its siblings and the composition knowledge that
+made the decision being tested.
+
+Component and prop names in these files resolve to `@starci/grammar/common`. Where the published
+contract offers no owner for a required behaviour, the audit records a capability gap rather than
+approving a local substitute.

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

@@ -0,0 +1,55 @@
+# UI proof
+
+Proof là tầng quyết định chỉ tồn tại sau khi trang đã render:
+
+```text
+business
+-> composition quyết định vùng, cấp độ, action, state và điểm nhấn
+-> presentation chốt giá trị CSS trên boundary do app sở hữu
+-> UI đã render  <- proof quan sát ở đây
+```
+
+Mọi rule trong folder này được operator audit tiêu thụ. Operator đó không truy cập được ý định, chỉ
+truy cập được đầu ra: cây accessibility đã được tính, phần tử đang thật sự giữ focus, khung hình nơi
+animation dừng lại, và tuyên bố mà trang cuối cùng đưa ra. Những chủ đề này nằm chung một chỗ vì
+không cái nào xác lập được bằng cách đọc source. Một rule `:focus-visible` không chứng minh có một
+chỉ dấu nhìn thấy được, một prop `label` không chứng minh một cái tên được tính ra, một thuộc tính
+`motion` không chứng minh một transition, và một bản copy đã duyệt không chứng minh điều mà trang
+render ra đang khẳng định. Vì vậy mỗi rule đều nêu quan sát nào sẽ bác bỏ nó, để một kết luận đạt
+luôn gọi tên được thứ đã thật sự được nhìn.
+
+## Danh mục
+
+| Knowledge | Quyết định điều gì | Rule |
+| --- | --- | --- |
+| [Accessibility](accessibility.vi.md) | Tên, quan hệ, kích thước mục tiêu và tương phản có tới được mọi người đọc không | A11Y-1 đến A11Y-4 |
+| [Contrast](contrast.vi.md) | Khác biệt và chữ có sống sót qua phép đo ở mọi theme và mọi state không | COLOR-3, COLOR-5 |
+| [Focus](focus.vi.md) | Focus nhìn thấy ở đâu, đi xa tới đâu, và quay về đâu | FOCUS-1 đến FOCUS-5 |
+| [Motion](motion.vi.md) | Ý nghĩa có sống sót khi chuyển động dừng, bị giảm hoặc bị cắt ngang không | MOTION-1 đến MOTION-4 |
+| [Render truth](render-truth.vi.md) | Mọi tuyên bố đã render có truy về được authority thật không | TRUTH-1 đến TRUTH-4 |
+
+## Cấu trúc rule
+
+`A11Y-1`, `FOCUS-5` và các tên `PREFIX-n` khác là địa chỉ thứ tự ổn định trong chủ đề của chúng. Con
+số không phải mức độ nghiêm trọng, cũng không phải một mức tuân thủ. Một chủ đề có thể công bố một
+dãy không liền số: `contrast.vi.md` chỉ công bố `COLOR-3` và `COLOR-5`, vì các số còn lại của tiền tố
+đó đã nghỉ cùng chủ đề sinh ra chúng và không bao giờ được dùng lại.
+
+Mỗi rule gồm heading, một dòng gọi tên thứ mà rule chi phối, và đúng một bảng:
+
+| Case | Dùng khi | Quan sát |
+| --- | --- | --- |
+| Case 1 | Tình huống đã render cụ thể dẫn tới rule này. | Bằng chứng runtime chính xác, và việc nhìn thấy nó sẽ bác bỏ điều gì. |
+
+Ô `Quan sát` gọi tên một thứ chụp được từ trang đang chạy, như một cái tên được tính ra, một phần tử
+đang active, một hình chữ nhật đã đo, một thời lượng đã tính, một kết quả đã truy vết, và nói rõ một
+quan sát ngược lại sẽ bác bỏ điều gì. Nó không bao giờ chỉ nhắc lại một ý định.
+
+Một case thuộc về rule hàng xóm thì không nằm trong bảng. Nó đứng thành một dòng ngay sau bảng, theo
+dạng `Không phải rule này: <điều kiện> thuộc PREFIX-n`. Mỗi file khép lại bằng mục
+`## File này không quyết định`, dẫn sang các file anh em và sang nhóm composition, nơi quyết định
+đang bị kiểm chứng đã được đưa ra.
+
+Tên component và tên prop trong các file này đều phải phân giải được về `@starci/grammar/common`. Ở
+đâu hợp đồng công khai chưa có owner cho một hành vi cần thiết, phần audit ghi nhận capability gap
+thay vì chấp nhận một giải pháp cục bộ.

package/knowledge/ui/proof/accessibility.md

@@ -0,0 +1,67 @@
+# Accessibility proof
+
+This file answers one question: in the tree that actually rendered, can every reader perceive and
+operate what the direction intended?
+
+Nothing here is settled by reading source. A prop in the source is an intention; the accessible name
+computed from the rendered node is the evidence. Each rule below states the observation that would
+falsify it, so a passing claim always names something that was looked at.
+
+## A11Y-1 — Field name and relationships
+
+Governs whether a field's identity and its current guidance reach assistive output.
+
+| Case | When | Observe |
+| --- | --- | --- |
+| Case 1 | A field renders with a visible label | The computed accessible name equals the visible label. A name supplied only by a placeholder, or a field with no name at all, falsifies it |
+| Case 2 | The field has a hint, an error, or both | The message is programmatically related to that input as its description, and the text is the current one. A visible message with no relation to the control falsifies it |
+| Case 3 | The field is required, invalid, or disabled | The rendered semantics match the current business facts. A red border with no invalid semantics falsifies it |
+| Case 4 | The reader types and validation runs again | The entered value survives the state change, and the description is the new one rather than a stale message |
+
+Not this rule: whether the failure was placed on the right owner in the first place is decided in
+composition, under FEEDBACK-1.
+
+## A11Y-2 — Glyph-only commands still carry a name
+
+Governs commands whose visible content is a glyph.
+
+| Case | When | Observe |
+| --- | --- | --- |
+| Case 1 | `IconButton` renders a glyph-only command | The button role carries an accessible name equal to its `label`. A tooltip as the only explanation falsifies it |
+| Case 2 | The button contains a decorative leading glyph | The inner glyph is hidden from assistive output. The same name computed twice, once on the button and once on the icon, falsifies it |
+| Case 3 | A standalone glyph itself carries meaning | `Icon.ariaLabel` produces an image role with that name. A meaningful glyph left hidden falsifies it |
+| Case 4 | The command can be disabled | Keyboard activation reaches it when enabled, and produces nothing when disabled |
+
+## A11Y-3 — Measurements have an accessible identity
+
+Governs numbers rendered as bars.
+
+| Case | When | Observe |
+| --- | --- | --- |
+| Case 1 | A resolved measurement renders | The progressbar exposes an accessible name equal to its label, the current value, a minimum of `0`, and a maximum of `100`, and that value equals the product fact |
+| Case 2 | The value has not resolved | The skeleton renders aria-hidden geometry with no progressbar and no label. A named progressbar announcing zero falsifies it |
+| Case 3 | `value` was omitted while data was unknown | The non-skeleton renderer defaults it, so the rendered output announces `0`, which falsifies the claim that the value is unknown |
+| Case 4 | A decorative bar sits beside the measurement | It carries no progressbar role. A second announced measurement for one fact falsifies the region |
+
+## A11Y-4 — Perceivable and operable at every required state
+
+Governs the evidence that closes an accessibility claim.
+
+| Case | When | Observe |
+| --- | --- | --- |
+| Case 1 | A target must be operable by touch | Accordion triggers and controls inside a rail measure at least `44px × 44px` in the current render. Any other target needs its own published contract before a minimum is asserted |
+| Case 2 | The task is attempted by keyboard alone | Every required control is reachable and operable. One unreachable required control falsifies the page |
+| Case 3 | The page is viewed in forced colours, at reduced contrast, or with colour removed | Every state, selection, and focus distinction survives. A distinction carried by fill alone falsifies it |
+| Case 4 | The page is zoomed, the text is scaled, or the viewport narrows | No required content and no focus indicator is clipped |
+| Case 5 | A family or the application styles over the published owner | The isolated published output, the family delta, and the application delta are compared separately, so the failing layer is named |
+
+Not this rule: which semantic owner should have been chosen is decided in composition, under
+HIERARCHY-1 and STATE-1.
+
+## What this file does not decide
+
+Which rank, action, or state the direction chose is [Hierarchy](../composition/hierarchy.md),
+[Action](../composition/action.md), and [State](../composition/state.md). Where the focus indicator
+goes and how far focus may travel is [Focus](focus.md). Whether animation removes meaning is
+[Motion](motion.md), and whether the rendered claim matches authority is
+[Render truth](render-truth.md).