@starci/skills 1.1.0

package/knowledge/ui/presentation/boundary.md

@@ -0,0 +1,170 @@
+# Boundary presentation
+
+This file answers one question: given an edge the application owns, which separator or border draws
+it, and which edge in a repeating set drops it?
+
+The theme publishes two hairline tokens and they mean different things: `--separator` draws the line
+between things, and `--border` draws the outline of one thing. A boundary inside a Grammar component
+is that component's, never the application's, and no application edge may be drawn with a raw colour
+value.
+
+## Catalog
+
+Boundaries have no value ramp, so the rule ID is an address over edge kinds rather than a position on
+a scale. Prefer the earliest rule that works: one seam before a per-row seam, a per-row seam before a
+parent declaration, a hairline before an outline.
+
+| Rule | Edge kind | Draws |
+| --- | --- | --- |
+| BOUNDARY-1 | One seam | The single line between two stacked bands |
+| BOUNDARY-2 | Per-row seam | Each row's own trailing line, dropped on the last row |
+| BOUNDARY-3 | Set seam | One declaration on the parent for every line inside a set |
+| BOUNDARY-4 | Inline seam | The line between columns of a grid or a split region |
+| BOUNDARY-5 | Outline | The border enclosing one object |
+| BOUNDARY-6 | No border | An object separated by elevation instead of a line |
+
+A repeating set has one line fewer than it has rows. Whichever rule draws the set, the outer edge of
+the last row is closed by the surface itself, so a set that renders a trailing line at its own edge
+has one boundary too many.
+
+## Owner
+
+Each case names who owns the edge. The owner decides whether the application writes a class at all.
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The edge belongs to the application | The class |
+| A component name | Common already draws this edge inside that component | Nothing. Pass the prop |
+| `—` | Common exposes no public path for this edge | The class, recorded as a workaround |
+
+Writing a class where a component is the owner is `APP_REIMPLEMENTATION`. Writing one where the owner
+is `—` stays linked to `COMMON_CAPABILITY_MISSING`. Adding an application line beside one a component
+already draws is `DOUBLE_OWNER`, and it renders as a visible double hairline.
+
+## Boundaries 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` | composer | BOUNDARY-1 |
+| `ChatWorkspace` | rail trigger boundary, hasRail, isCompactRail | BOUNDARY-1 |
+| `Divider` | span | BOUNDARY-5 |
+| `MediaFrame` | root, treatment!="plain" | BOUNDARY-5 |
+| `NavigationFeatureNav` | root | BOUNDARY-1 |
+| `StaticStateRow` | root | BOUNDARY-3 |
+| `Subnav` | root | BOUNDARY-1 |
+| `SurfaceAccordionCard` | accordion row | BOUNDARY-3 |
+| `SurfaceAccordionCard` | accordion shell, depth="nested" | BOUNDARY-5 |
+| `SurfaceAccordionCard` | accordion shell, depth="top" | BOUNDARY-6 |
+| `SurfaceCard` | card content, depth!="nested" | BOUNDARY-6 |
+| `SurfaceCard` | card content, depth="nested" | BOUNDARY-5 |
+| `WorkspaceShell` | compact navigation, hasCompactNavigation | BOUNDARY-1 |
+| `WorkspaceShell` | leading rule, railPosition="leading" | BOUNDARY-4 |
+
+## BOUNDARY-1 — `border-t border-separator` / `--separator`
+
+One seam between two stacked bands inside a flush surface. The bands touch, and the line is what
+tells them apart.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Two app-owned bands stacked inside one joined card | `—` | `<div aria-hidden className="border-t border-separator" />` between them |
+| Case 2 | A band that carries its own leading seam rather than a separate element | `—` | `<div className="min-w-0 border-t border-separator">` on the band itself |
+| Case 3 | A card's closing action band, separated from the content above it | `—` | `<div className="border-t border-separator px-4 pb-4 pt-3">` |
+| Case 4 | The block edge of page chrome against the content below it | `Subnav`, `NavigationFeatureNav` | Compose the component; no border class |
+
+Not this rule: three or more rows of the same kind. Use BOUNDARY-2 or BOUNDARY-3.
+
+A separator element is decorative and takes `aria-hidden`; the bands it divides carry the meaning.
+
+## BOUNDARY-2 — `border-b border-separator last:border-b-0` / `--separator`
+
+A repeating set where every row draws its own trailing line, and the last row drops it because the
+surface's own edge already closes the set.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Rows of one collection rendered edge to edge inside a joined card | `—` | `<li className="border-b border-separator px-4 py-3 last:border-b-0">` |
+| Case 2 | The same set where the trailing row also opens up to the card's outer inset | `—` | The same class plus `last:pb-4` |
+| Case 3 | A grid of the same rows, where the last full row of the set drops the line | `—` | `sm:[&:nth-last-child(-n+2)]:border-b-0` on a two-column set |
+
+Not this rule: a set whose rows carry no class of their own. Use BOUNDARY-3.
+
+`last:border-b-0` is the whole point of this rule, not an embellishment. Without it the set renders a
+line against the surface edge and the card reads as unfinished. Case 3 exists because in a two-column
+grid the last row is the last two children, so `last:` alone drops one line and leaves its neighbour.
+
+## BOUNDARY-3 — `divide-y divide-separator` / `--separator`
+
+One declaration on the parent draws every line inside a set. The rows say nothing, so no row can be
+missed and no row can render a line the set did not intend.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A list whose rows are uniform and need no per-row exception | `—` | `<ul className="m-0 list-none p-0 divide-y divide-separator">` |
+| Case 2 | A grid of peer measures stacked on one axis | `—` | `<div className="grid min-w-0 grid-cols-1 divide-y divide-separator">` |
+| Case 3 | A list or disclosure whose rows Common already separates | `StaticStateRow`, `SurfaceAccordionCard` | Compose the rows; no divide class |
+
+Not this rule: a set where individual rows need a different edge. Use BOUNDARY-2.
+
+Common draws Case 3 with an adjacent-sibling rule rather than a parent declaration. Both mean the same
+thing, one line between consecutive rows and none at either outer edge, so both satisfy this rule.
+
+## BOUNDARY-4 — `border-l` / `divide-x` / `--separator`
+
+A seam on the inline axis, between columns of a grid or between the two halves of a split region. It
+appears only at the width where the columns exist.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A set that stacks on narrow widths and becomes columns on wide ones | `—` | `divide-y divide-separator lg:divide-y-0 lg:divide-x` on the parent |
+| Case 2 | A two-column grid where only the starting column carries the column seam | `—` | `sm:[&:nth-child(odd)]:border-r` on the row class |
+| Case 3 | A panel that becomes a side region and needs one seam against the primary column | `—` | `lg:border-l lg:border-separator` on the panel |
+| Case 4 | A shell whose leading rail is separated from the primary region by a rule | `WorkspaceShell` | Compose the shell; no border class |
+
+Not this rule: the block-axis lines of the same set. Those stay BOUNDARY-2 or BOUNDARY-3, and the two
+axes each name their own case.
+
+The `nth-child` selector in Case 2 is what keeps the trailing column from drawing a line against the
+surface edge. It is the inline-axis form of `last:border-b-0`.
+
+## BOUNDARY-5 — `border` / `--border`
+
+The outline enclosing one object, rather than a line between two. Every case belongs to a Grammar
+component, because the objects that need an outline are Grammar's.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A card nested inside another bounded surface | `SurfaceCard` | `depth="nested"` already draws the outline |
+| Case 2 | A framed media viewport | `MediaFrame` | Compose the frame; no border class |
+| Case 3 | A code block or a table frame inside article content | `FencedCodeBlock`, `MarkdownTableFrame` | Compose the block; no border class |
+| Case 4 | A labelled boundary offering an alternative between two paths | `Divider` | `<Divider label="or" />` |
+
+Not this rule: the line between two touching bands. That is a hairline on `--separator`, so use
+BOUNDARY-1.
+
+## BOUNDARY-6 — no border / `--shadow-surface`
+
+An object separated from the page by elevation rather than by a line. This is the default face of a
+top-level card, and it is a boundary decision even though it draws no border.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A top-level card sitting directly on the page canvas | `SurfaceCard` | `depth="top"` already clears the border and applies the shadow |
+| Case 2 | The same card once it is nested inside another surface | `SurfaceCard` | `depth="nested"` replaces the shadow with BOUNDARY-5 |
+
+Not this rule: adding an outline to a top-level card. The border and the shadow are alternatives, and
+drawing both is `DOUBLE_OWNER`.
+
+`--shadow-surface` is a theme hook rather than a fixed value, and a theme may resolve it to no shadow
+at all. A top-level card is then separated by its face against the page canvas alone, which is a
+surface decision and belongs to [Surface](surface.md).
+
+## What this file does not decide
+
+Which face sits on either side of an edge is [Surface](surface.md). The space between an edge and its
+content is [Padding](padding.md), and a boundary drawn by a line rather than by space is why a
+separator-facing side takes less inset than an outer edge. Distance between siblings that need no line
+is [Gap](gap.md), and the clipping that keeps a full-bleed band inside its card is
+[Overflow](overflow.md).

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

@@ -0,0 +1,169 @@
+# Boundary presentation
+
+File này trả lời đúng một câu hỏi: một cạnh mà ứng dụng sở hữu thì được vẽ bằng separator hay border
+nào, và cạnh nào trong một tập lặp lại thì bỏ đường kẻ đó.
+
+Theme công bố hai token đường mảnh và chúng mang hai nghĩa khác nhau: `--separator` vẽ đường giữa
+những thứ khác nhau, còn `--border` vẽ đường viền của một thứ. Ranh giới bên trong một Grammar
+component là của chính component đó, không bao giờ của ứng dụng, và không cạnh nào của ứng dụng được
+vẽ bằng một giá trị màu thô.
+
+## Danh mục
+
+Boundary không có thang giá trị, nên số của rule là địa chỉ trên tập các loại cạnh chứ không phải vị
+trí trên một dải. Ưu tiên rule đứng trước nếu nó đủ dùng: một đường trước đường theo từng hàng, đường
+theo từng hàng trước khai báo ở cha, đường mảnh trước đường viền.
+
+| Rule | Loại cạnh | Vẽ cái gì |
+| --- | --- | --- |
+| BOUNDARY-1 | Một đường | Đường duy nhất giữa hai dải xếp chồng |
+| BOUNDARY-2 | Đường theo từng hàng | Đường cuối của mỗi hàng, bỏ ở hàng cuối |
+| BOUNDARY-3 | Đường của cả tập | Một khai báo ở cha vẽ mọi đường bên trong tập |
+| BOUNDARY-4 | Đường theo trục inline | Đường giữa các cột của grid hoặc của một vùng chẻ đôi |
+| BOUNDARY-5 | Đường viền | Border bao quanh một đối tượng |
+| BOUNDARY-6 | Không border | Đối tượng được tách bằng độ nổi thay vì bằng đường kẻ |
+
+Một tập lặp lại có số đường ít hơn số hàng đúng một. Rule nào vẽ tập cũng vậy, mép ngoài của hàng cuối
+đã do chính surface đóng lại, nên một tập còn vẽ đường ở mép của chính nó là thừa một ranh giới.
+
+## Owner
+
+Mỗi case gọi tên ai sở hữu cạnh đó. Owner quyết định ứng dụng có được viết class hay không.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Cạnh thuộc về ứng dụng | Viết class |
+| Tên component | Common đã vẽ cạnh này bên trong component đó | Không viết gì, chỉ truyền prop |
+| `—` | Common chưa có đường dùng công khai cho cạnh này | Viết class, ghi nhận là workaround |
+
+Viết class ở chỗ owner là một component chính là `APP_REIMPLEMENTATION`. Viết class ở chỗ owner là `—`
+thì gắn liền với `COMMON_CAPABILITY_MISSING`. Thêm một đường của ứng dụng cạnh đường mà component đã
+vẽ là `DOUBLE_OWNER`, và nó hiện ra thành một đường mảnh đôi nhìn thấy được.
+
+## Boundary 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` | composer | BOUNDARY-1 |
+| `ChatWorkspace` | rail trigger boundary, hasRail, isCompactRail | BOUNDARY-1 |
+| `Divider` | span | BOUNDARY-5 |
+| `MediaFrame` | root, treatment!="plain" | BOUNDARY-5 |
+| `NavigationFeatureNav` | root | BOUNDARY-1 |
+| `StaticStateRow` | root | BOUNDARY-3 |
+| `Subnav` | root | BOUNDARY-1 |
+| `SurfaceAccordionCard` | accordion row | BOUNDARY-3 |
+| `SurfaceAccordionCard` | accordion shell, depth="nested" | BOUNDARY-5 |
+| `SurfaceAccordionCard` | accordion shell, depth="top" | BOUNDARY-6 |
+| `SurfaceCard` | card content, depth!="nested" | BOUNDARY-6 |
+| `SurfaceCard` | card content, depth="nested" | BOUNDARY-5 |
+| `WorkspaceShell` | compact navigation, hasCompactNavigation | BOUNDARY-1 |
+| `WorkspaceShell` | leading rule, railPosition="leading" | BOUNDARY-4 |
+
+## BOUNDARY-1 — `border-t border-separator` / `--separator`
+
+Một đường giữa hai dải xếp chồng bên trong một surface tràn viền. Hai dải chạm nhau, và đường kẻ là
+thứ phân biệt chúng.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Hai dải do app sở hữu xếp chồng trong một card nối liền | `—` | `<div aria-hidden className="border-t border-separator" />` đặt giữa hai dải |
+| Case 2 | Một dải tự mang đường dẫn đầu của nó thay vì một phần tử riêng | `—` | `<div className="min-w-0 border-t border-separator">` trên chính dải đó |
+| Case 3 | Dải action đóng lại của một card, tách khỏi nội dung phía trên | `—` | `<div className="border-t border-separator px-4 pb-4 pt-3">` |
+| Case 4 | Mép block của chrome trang đối với nội dung bên dưới | `Subnav`, `NavigationFeatureNav` | Ghép component, không viết class border |
+
+Không phải rule này: từ ba hàng cùng loại trở lên thì dùng BOUNDARY-2 hoặc BOUNDARY-3.
+
+Một phần tử separator là trang trí và phải mang `aria-hidden`; nghĩa nằm ở các dải mà nó chia.
+
+## BOUNDARY-2 — `border-b border-separator last:border-b-0` / `--separator`
+
+Một tập lặp lại mà mỗi hàng tự vẽ đường kết của nó, còn hàng cuối bỏ đường đó vì mép của chính surface
+đã đóng tập lại rồi.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Các hàng của một tập hợp render sát hai mép trong card nối liền | `—` | `<li className="border-b border-separator px-4 py-3 last:border-b-0">` |
+| Case 2 | Cũng tập đó, khi hàng cuối còn mở ra tới inset mép ngoài của card | `—` | Cùng class, thêm `last:pb-4` |
+| Case 3 | Một lưới cùng loại hàng, nơi hàng đầy đủ cuối cùng của tập bỏ đường kẻ | `—` | `sm:[&:nth-last-child(-n+2)]:border-b-0` trên tập hai cột |
+
+Không phải rule này: một tập mà các hàng không mang class riêng thì dùng BOUNDARY-3.
+
+`last:border-b-0` chính là trọng tâm của rule này, không phải phần trang trí. Thiếu nó thì tập render
+một đường sát mép surface và card đọc lên như chưa hoàn thiện. Case 3 tồn tại vì trong lưới hai cột thì
+hàng cuối là hai con cuối, nên chỉ dùng `last:` sẽ bỏ được một đường và bỏ sót đường bên cạnh.
+
+## BOUNDARY-3 — `divide-y divide-separator` / `--separator`
+
+Một khai báo ở cha vẽ mọi đường bên trong tập. Các hàng không nói gì, nên không hàng nào bị bỏ sót và
+không hàng nào render được một đường mà tập không định vẽ.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một list mà các hàng đồng nhất và không cần ngoại lệ theo hàng | `—` | `<ul className="m-0 list-none p-0 divide-y divide-separator">` |
+| Case 2 | Một lưới các số đo ngang hàng xếp chồng trên một trục | `—` | `<div className="grid min-w-0 grid-cols-1 divide-y divide-separator">` |
+| Case 3 | Một list hay disclosure mà Common đã tách hàng sẵn | `StaticStateRow`, `SurfaceAccordionCard` | Ghép hàng, không viết class divide |
+
+Không phải rule này: một tập mà từng hàng cần cạnh khác nhau thì dùng BOUNDARY-2.
+
+Common vẽ Case 3 bằng luật anh em kề chứ không bằng khai báo ở cha. Hai cách cùng một nghĩa, một đường
+giữa hai hàng liên tiếp và không đường nào ở hai mép ngoài, nên cả hai đều thoả rule này.
+
+## BOUNDARY-4 — `border-l` / `divide-x` / `--separator`
+
+Một đường trên trục inline, giữa các cột của một lưới hoặc giữa hai nửa của một vùng chẻ đôi. Nó chỉ
+xuất hiện ở bề rộng mà các cột thực sự tồn tại.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một tập xếp chồng ở khổ hẹp và thành cột ở khổ rộng | `—` | `divide-y divide-separator lg:divide-y-0 lg:divide-x` trên cha |
+| Case 2 | Lưới hai cột mà chỉ cột đầu mang đường ngăn cột | `—` | `sm:[&:nth-child(odd)]:border-r` trên class của hàng |
+| Case 3 | Một panel trở thành vùng bên và cần một đường với cột chính | `—` | `lg:border-l lg:border-separator` trên panel |
+| Case 4 | Một shell mà rail dẫn đầu được tách khỏi vùng chính bằng một đường kẻ | `WorkspaceShell` | Ghép shell, không viết class border |
+
+Không phải rule này: các đường theo trục block của cùng tập đó. Chúng vẫn là BOUNDARY-2 hoặc
+BOUNDARY-3, và mỗi trục phải gọi tên case của riêng nó.
+
+Selector `nth-child` ở Case 2 chính là thứ giữ cho cột cuối không vẽ đường sát mép surface. Nó là dạng
+trục inline của `last:border-b-0`.
+
+## BOUNDARY-5 — `border` / `--border`
+
+Đường viền bao quanh một đối tượng, chứ không phải đường giữa hai thứ. Mọi case đều thuộc về một
+Grammar component, vì những đối tượng cần đường viền đều là của Grammar.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một card lồng bên trong một surface có ranh giới khác | `SurfaceCard` | `depth="nested"` đã vẽ sẵn đường viền |
+| Case 2 | Một viewport media có khung | `MediaFrame` | Ghép frame, không viết class border |
+| Case 3 | Một khối code hay khung bảng trong nội dung article | `FencedCodeBlock`, `MarkdownTableFrame` | Ghép khối, không viết class border |
+| Case 4 | Một ranh giới có nhãn nêu ra lựa chọn thay thế giữa hai đường đi | `Divider` | `<Divider label="hoặc" />` |
+
+Không phải rule này: đường giữa hai dải chạm nhau. Đó là đường mảnh trên `--separator`, nên dùng
+BOUNDARY-1.
+
+## BOUNDARY-6 — không border / `--shadow-surface`
+
+Một đối tượng được tách khỏi trang bằng độ nổi thay vì bằng đường kẻ. Đây là mặt mặc định của card cấp
+cao nhất, và nó vẫn là một quyết định ranh giới dù không vẽ border nào.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một card cấp cao nhất nằm thẳng trên canvas trang | `SurfaceCard` | `depth="top"` đã bỏ sẵn border và áp bóng đổ |
+| Case 2 | Cũng card đó khi nó được lồng vào bên trong một surface khác | `SurfaceCard` | `depth="nested"` thay bóng đổ bằng BOUNDARY-5 |
+
+Không phải rule này: thêm đường viền cho một card cấp cao nhất. Border và bóng đổ là hai lựa chọn thay
+thế nhau, vẽ cả hai là `DOUBLE_OWNER`.
+
+`--shadow-surface` là một điểm móc của theme chứ không phải giá trị cố định, và một theme có thể quy nó
+về không bóng đổ. Khi đó card cấp cao nhất chỉ còn được tách bằng chính mặt của nó trên canvas trang,
+và đó là quyết định surface, thuộc về [Surface](surface.md).
+
+## File này không quyết định
+
+Mặt nào nằm ở hai bên một cạnh là việc của [Surface](surface.md). Khoảng cách giữa một cạnh và nội
+dung của nó là [Padding](padding.md), và một ranh giới được vẽ bằng đường kẻ thay vì bằng khoảng trắng
+chính là lý do cạnh giáp separator lấy inset nhỏ hơn cạnh mép ngoài. Khoảng cách giữa các phần tử ngang
+hàng mà không cần đường kẻ là [Gap](gap.md), còn việc cắt để giữ một dải tràn viền nằm gọn trong card
+là [Overflow](overflow.md).

package/knowledge/ui/presentation/font.md

@@ -0,0 +1,155 @@
+# Font presentation
+
+This file answers one question: given a line of copy the application has already ranked, which public
+typography prop renders it?
+
+Composition has already chosen the DOM tree and the Grammar objects. The application decides the
+information rank. Grammar renders that rank. The application never writes a size, weight, line height,
+or tracking class, and never overrides typography inside another Grammar component.
+
+## Scale
+
+The type scale is closed and shared by `Text` and `Heading`. The rule ID is the ordinal position on
+that scale, smallest first. It is not a Tailwind step and not a heading level.
+
+| Rule | Rendered | `Text` | `Heading` |
+| --- | --- | --- | --- |
+| FONT-1 | `text-xs` / `leading-4` | `size="xs"` | `level={4}` |
+| FONT-2 | `text-sm` / `leading-5` | `size="sm"` | `level={3}` |
+| FONT-3 | `text-base` / `leading-6` | `size="md"`, the default | `level={2}` |
+| FONT-4 | `text-xl` | none | `level={1}` |
+| FONT-5 | `text-3xl` / `leading-9` | `size="metric-lead"` | none |
+| FONT-6 | `text-4xl` / `leading-tight` | none | `scale="display"` |
+
+`Text` and `Heading` are not interchangeable at the same size. A heading declares document structure;
+a text line does not. Choosing `Heading` to obtain a size, or `Text` to avoid an outline entry, is a
+structure error rather than a typography one.
+
+Tracking is not an application decision. `Heading` applies `tracking-tight` at FONT-4 and FONT-6 only.
+
+## Owner
+
+Typography belongs to Grammar. The owner cell names which component renders the rank.
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| A component name | `Text` or `Heading` renders this rank | The prop only |
+| `—` | The rank has no public prop | Nothing. Report the gap |
+
+There is no `App` owner in this file. An application typography class is `APP_OVERRIDE`, and a raw
+`font-size` or `font-weight` that changes semantic rank is rejected even when the pixels match.
+
+## Font 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` | rail trigger, hasRail, isCompactRail | FONT-2 |
+| `Heading` | root, scale!="display", level=1 | FONT-4 |
+| `Heading` | root, scale!="display", level=2 | FONT-3 |
+| `Heading` | root, scale!="display", level=3 | FONT-2 |
+| `Heading` | root, scale!="display", level=4 | FONT-1 |
+| `Heading` | root, scale="display" | FONT-6 |
+| `Input` | toggle label, not (!isSecret || toggleLabel === undefined), ToggleIcon=undefined | FONT-1 |
+| `Label` | root, depth!="nested" | FONT-2 |
+| `Label` | root, depth="nested" | FONT-1 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | FONT-1 |
+| `Sidebar` | item label, not collapsed | FONT-2 |
+| `SurfaceListCard` | fact, not (label === undefined || labelHidden), fact!=undefined, depth!="nested" | FONT-2 |
+| `SurfaceListCard` | fact, not (label === undefined || labelHidden), fact!=undefined, depth="nested" | FONT-1 |
+| `Text` | root, size="md" | FONT-3 |
+| `Text` | root, size="metric-lead" | FONT-5 |
+| `Text` | root, size="sm" | FONT-2 |
+| `Text` | root, size="xs" | FONT-1 |
+| `TextAction` | root, size="md" | FONT-3 |
+| `TextAction` | root, size="sm" | FONT-2 |
+| `TextAction` | root, size="xs" | FONT-1 |
+| `Tooltip` | content | FONT-1 |
+
+## FONT-1 — `text-xs` / `leading-4`
+
+The smallest public size, for the lowest rank of supporting information.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Brief metadata that stays understandable at the smallest size | `Text` | `<Text size="xs">Optional</Text>` |
+| Case 2 | The label of a nested region inside an already-titled section | `Heading` | `<Heading level={4}>Card details</Heading>` |
+
+`Text size="xs"` always resolves to muted and cannot be promoted to another tone. `Heading level={4}`
+carries the same muted treatment.
+
+Not this rule: ordinary sentences, or any fact the reader must not miss. Use FONT-2 or FONT-3.
+
+## FONT-2 — `text-sm` / `leading-5`
+
+A compact reading size for supporting copy that still forms complete lines.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A complete line ranked below normal body copy, such as a timestamp or short fact | `Text` | `<Text size="sm">Updated 2 minutes ago</Text>` |
+| Case 2 | A third-level region heading inside a section | `Heading` | `<Heading level={3}>Payment method</Heading>` |
+
+Not this rule: shrinking body copy so it fits a container that is too small. Fix the container.
+
+## FONT-3 — `text-base` / `leading-6`
+
+The normal reading size, and the resolved default when no size is given.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Ordinary explanatory copy with normal reading priority | `Text` | `<Text>Your subscription renews on 12 March.</Text>` |
+| Case 2 | The heading of a section inside a page | `Heading` | `<Heading level={2}>Billing</Heading>` |
+
+## FONT-4 — `text-xl`
+
+The page-level heading size, carrying tight tracking.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | The single heading that names the whole page or route | `Heading` | `<Heading level={1}>Account</Heading>` |
+
+Not this rule: a second `level={1}` on the same page. One document, one top-level heading.
+
+## FONT-5 — `text-3xl` / `leading-9`
+
+A large numeric treatment for one already-important value.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | The single leading metric or short value that is the main fact of its region | `Text` | `<Text size="metric-lead" weight="semibold">84%</Text>` |
+
+Not this rule: sentences, decoration, or imitating a heading. It creates no heading semantics.
+
+## FONT-6 — `text-4xl` / `leading-tight`
+
+Display emphasis applied to a heading that keeps its semantic level.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A page-root heading that must carry marketing or landing weight | `Heading` | `<Heading level={1} scale="display">Learn without limits</Heading>` |
+
+Not this rule: raising the visual size of a nested heading. `scale` changes the recipe, never the
+outline position.
+
+## Weight
+
+Weight is a second axis, not a position on the size scale. Its public set is closed.
+
+| Prop | Rendered | Use for |
+| --- | --- | --- |
+| `weight="normal"` | `font-normal`, the default | Reading copy and ordinary facts |
+| `weight="medium"` | `font-medium` | A compact label, or a title above its own description |
+| `weight="semibold"` | `font-semibold` | A fact that must be found first within its region |
+
+Weight refines a rank the application has already chosen. It never manufactures a new hierarchy
+level, and it never substitutes for a heading. `Heading` applies its own weight per level and takes
+no weight prop.
+
+Bold beyond `semibold` has no public prop. Treat an intent that needs it as a gap rather than writing
+a class.
+
+## What this file does not decide
+
+Which colour expresses the rank is [Tone](tone.md). How the line wraps, aligns, or truncates is
+[Text flow](text-flow.md). How much room the text region gets is [Measure](measure.md).

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

@@ -0,0 +1,156 @@
+# Font presentation
+
+File này trả lời đúng một câu hỏi: một dòng chữ mà ứng dụng đã xếp hạng xong thì render bằng prop
+typography công khai nào.
+
+Bước composition đã chọn xong cây DOM và các Grammar object. Ứng dụng quyết định hạng thông tin,
+Grammar render hạng đó. Ứng dụng không bao giờ viết class cỡ chữ, độ đậm, line height hay tracking,
+và không ghi đè typography bên trong một Grammar component khác.
+
+## Thang giá trị
+
+Thang chữ là thang đóng, dùng chung cho `Text` và `Heading`. Số của rule là thứ tự trên thang đó,
+nhỏ trước. Nó không phải bậc Tailwind và cũng không phải cấp heading.
+
+| Rule | Render ra | `Text` | `Heading` |
+| --- | --- | --- | --- |
+| FONT-1 | `text-xs` / `leading-4` | `size="xs"` | `level={4}` |
+| FONT-2 | `text-sm` / `leading-5` | `size="sm"` | `level={3}` |
+| FONT-3 | `text-base` / `leading-6` | `size="md"`, mặc định | `level={2}` |
+| FONT-4 | `text-xl` | không có | `level={1}` |
+| FONT-5 | `text-3xl` / `leading-9` | `size="metric-lead"` | không có |
+| FONT-6 | `text-4xl` / `leading-tight` | không có | `scale="display"` |
+
+`Text` và `Heading` không thay thế nhau được dù cùng cỡ. Heading khai báo cấu trúc tài liệu, còn một
+dòng text thì không. Chọn `Heading` để lấy cỡ chữ, hoặc chọn `Text` để né một mục trong dàn bài, là
+lỗi cấu trúc chứ không phải lỗi typography.
+
+Tracking không phải quyết định của ứng dụng. `Heading` chỉ áp `tracking-tight` ở FONT-4 và FONT-6.
+
+## Owner
+
+Typography thuộc về Grammar. Ô owner gọi tên component nào render hạng đó.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| Tên component | `Text` hoặc `Heading` render hạng này | Chỉ truyền prop |
+| `—` | Hạng này chưa có prop công khai | Không viết gì, báo là thiếu |
+
+File này không có owner `App`. Một class typography do ứng dụng viết là `APP_OVERRIDE`, và một
+`font-size` hay `font-weight` thô làm đổi hạng ngữ nghĩa thì bị từ chối kể cả khi pixel trùng khớp.
+
+## Font 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` | rail trigger, hasRail, isCompactRail | FONT-2 |
+| `Heading` | root, scale!="display", level=1 | FONT-4 |
+| `Heading` | root, scale!="display", level=2 | FONT-3 |
+| `Heading` | root, scale!="display", level=3 | FONT-2 |
+| `Heading` | root, scale!="display", level=4 | FONT-1 |
+| `Heading` | root, scale="display" | FONT-6 |
+| `Input` | toggle label, not (!isSecret || toggleLabel === undefined), ToggleIcon=undefined | FONT-1 |
+| `Label` | root, depth!="nested" | FONT-2 |
+| `Label` | root, depth="nested" | FONT-1 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | FONT-1 |
+| `Sidebar` | item label, not collapsed | FONT-2 |
+| `SurfaceListCard` | fact, not (label === undefined || labelHidden), fact!=undefined, depth!="nested" | FONT-2 |
+| `SurfaceListCard` | fact, not (label === undefined || labelHidden), fact!=undefined, depth="nested" | FONT-1 |
+| `Text` | root, size="md" | FONT-3 |
+| `Text` | root, size="metric-lead" | FONT-5 |
+| `Text` | root, size="sm" | FONT-2 |
+| `Text` | root, size="xs" | FONT-1 |
+| `TextAction` | root, size="md" | FONT-3 |
+| `TextAction` | root, size="sm" | FONT-2 |
+| `TextAction` | root, size="xs" | FONT-1 |
+| `Tooltip` | content | FONT-1 |
+
+## FONT-1 — `text-xs` / `leading-4`
+
+Cỡ công khai nhỏ nhất, cho hạng thông tin phụ thấp nhất.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Metadata ngắn, vẫn hiểu được ở cỡ nhỏ nhất | `Text` | `<Text size="xs">Optional</Text>` |
+| Case 2 | Nhãn của một vùng lồng bên trong một section đã có tiêu đề | `Heading` | `<Heading level={4}>Card details</Heading>` |
+
+`Text size="xs"` luôn quy về muted và không nâng lên tone khác được. `Heading level={4}` mang đúng
+cách xử lý muted đó.
+
+Không phải rule này: câu văn thường, hoặc bất kỳ dữ kiện nào người đọc không được bỏ sót. Dùng
+FONT-2 hoặc FONT-3.
+
+## FONT-2 — `text-sm` / `leading-5`
+
+Cỡ đọc gọn cho phần copy phụ nhưng vẫn thành câu hoàn chỉnh.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một dòng hoàn chỉnh xếp dưới body copy thường, kiểu mốc thời gian hay một dữ kiện ngắn | `Text` | `<Text size="sm">Updated 2 minutes ago</Text>` |
+| Case 2 | Tiêu đề vùng cấp ba bên trong một section | `Heading` | `<Heading level={3}>Payment method</Heading>` |
+
+Không phải rule này: thu nhỏ body copy cho vừa một container quá chật. Sửa cái container.
+
+## FONT-3 — `text-base` / `leading-6`
+
+Cỡ đọc thường, và là giá trị mặc định khi không truyền size.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Copy giải thích thông thường, ưu tiên đọc ở mức bình thường | `Text` | `<Text>Your subscription renews on 12 March.</Text>` |
+| Case 2 | Tiêu đề của một section bên trong trang | `Heading` | `<Heading level={2}>Billing</Heading>` |
+
+## FONT-4 — `text-xl`
+
+Cỡ tiêu đề cấp trang, mang tracking chặt.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Tiêu đề duy nhất gọi tên cả trang hoặc cả route | `Heading` | `<Heading level={1}>Account</Heading>` |
+
+Không phải rule này: một `level={1}` thứ hai trên cùng trang. Một tài liệu, một tiêu đề cấp cao nhất.
+
+## FONT-5 — `text-3xl` / `leading-9`
+
+Cách trình bày số lớn cho một giá trị vốn đã quan trọng.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Chỉ số hoặc giá trị ngắn duy nhất, là dữ kiện chính của vùng đó | `Text` | `<Text size="metric-lead" weight="semibold">84%</Text>` |
+
+Không phải rule này: câu văn, trang trí, hoặc giả làm tiêu đề. Nó không tạo ra ngữ nghĩa heading nào.
+
+## FONT-6 — `text-4xl` / `leading-tight`
+
+Nhấn mạnh cỡ display áp lên một heading vẫn giữ nguyên cấp ngữ nghĩa của nó.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Tiêu đề gốc trang cần sức nặng kiểu landing hoặc marketing | `Heading` | `<Heading level={1} scale="display">Learn without limits</Heading>` |
+
+Không phải rule này: phóng to một heading lồng bên trong. `scale` đổi công thức hiển thị chứ không
+bao giờ đổi vị trí trong dàn bài.
+
+## Độ đậm
+
+Độ đậm là trục thứ hai, không phải một vị trí trên thang cỡ chữ. Tập giá trị công khai của nó là
+tập đóng.
+
+| Prop | Render ra | Dùng cho |
+| --- | --- | --- |
+| `weight="normal"` | `font-normal`, mặc định | Copy để đọc và các dữ kiện thường |
+| `weight="medium"` | `font-medium` | Một nhãn gọn, hoặc một tiêu đề nằm trên phần mô tả của chính nó |
+| `weight="semibold"` | `font-semibold` | Dữ kiện phải tìm thấy đầu tiên trong vùng của nó |
+
+Độ đậm chỉ tinh chỉnh một hạng mà ứng dụng đã chọn. Nó không đẻ ra một cấp phân cấp mới, và không
+thay thế được một heading. `Heading` tự áp độ đậm theo từng cấp và không nhận prop weight.
+
+Đậm hơn `semibold` chưa có prop công khai. Ý đồ nào cần tới nó thì coi là thiếu capability, đừng
+viết class.
+
+## File này không quyết định
+
+Màu nào diễn đạt hạng đó thuộc về [Tone](tone.md). Dòng chữ xuống dòng, canh lề hay cắt bớt ra sao
+thuộc về [Text flow](text-flow.md). Vùng chữ được bao nhiêu chỗ thuộc về [Measure](measure.md).