@starci/skills 1.1.0

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

@@ -0,0 +1,292 @@
+# Padding presentation
+
+File này trả lời đúng một câu hỏi: một ranh giới do ứng dụng sở hữu thì cách nội dung của nó bao xa.
+
+Bước composition đã chọn xong cây DOM và các Grammar object. Padding presentation chỉ giải quyết
+phần inset của page, section và container do ứng dụng sở hữu. Inset bên trong một card, input,
+button hay bất kỳ Grammar object nào khác đều thuộc về Grammar.
+
+## 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ừ PADDING-5 trở đi.
+
+| Rule | Class | Giá trị | Token Common |
+| --- | --- | --- | --- |
+| PADDING-0 | `p-0` | `0` | không có |
+| PADDING-1 | `p-1` | `.25rem` | không có |
+| PADDING-2 | `p-2` | `.5rem` | không có |
+| PADDING-3 | `p-3` | `.75rem` | không có |
+| PADDING-4 | `p-4` | `1rem` | không có |
+| PADDING-5 | `p-6` | `1.5rem` | không có |
+| PADDING-6 | `p-8` | `2rem` | không có |
+
+Common không publish token padding nào. Các inset bên dưới chỉ đến được qua chính component sở hữu
+chúng, chứ không qua một biến mà ứng dụng được phép đặt.
+
+Page inset là ngoại lệ duy nhất và không nằm trên thang này: `--grammar-page-inset` cho ra
+`clamp(1rem, 3vw, 2rem)`, một giá trị responsive do `PageContainer` sở hữu. Ứng dụng không bao giờ
+dựng lại nó bằng một class cố định.
+
+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 inset. Owner quyết định ứng dụng có được viết class hay không.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Ranh giới thuộc về ứng dụng | Viết class |
+| Tên component | Common đã áp inset bên trong component đó | Không viết gì, chỉ ghép component |
+| `—` | Common chưa có đường dùng công khai cho ranh giới 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ò vào ruột một Grammar
+component bằng selector hoặc bằng class truyền vào để đổi inset của nó là `APP_OVERRIDE`.
+
+## Padding 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 body, hasRail, isCompactRail | PADDING-0 |
+| `ChatWorkspace` | overlay rail, hasRail, isCompactRail | PADDING-4 |
+| `ChatWorkspace` | overlay rail, hasRail, not isCompactRail | PADDING-4 |
+| `ChatWorkspace` | rail trigger boundary, hasRail, isCompactRail | PADDING-2 |
+| `ChatWorkspace` | rail trigger boundary, hasRail, isCompactRail | PADDING-4 |
+| `ChatWorkspace` | rail trigger, hasRail, isCompactRail | PADDING-3 |
+| `EmptyNotice` | root | PADDING-4 |
+| `HorizontalScrollRegion` | root | PADDING-1 |
+| `NavigationFeatureNav` | primary | PADDING-3 |
+| `OtpInput` | root | PADDING-1 |
+| `Rail` | body, inset="content" | PADDING-3 |
+| `Rail` | body, inset="content" | PADDING-5 |
+| `Sidebar` | footer, not (collapsed || footer == null) | PADDING-0 |
+| `Sidebar` | footer, not (collapsed || footer == null) | PADDING-3 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | PADDING-1 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | PADDING-2 |
+| `Sidebar` | group label, group.label!=undefined, not collapsed | PADDING-3 |
+| `Sidebar` | header, not (collapsed || header == null) | PADDING-3 |
+| `Sidebar` | icon button wrapper, canToggle | PADDING-2 |
+| `Sidebar` | list box item, not collapsed | PADDING-2 |
+| `Sidebar` | list box item, not collapsed | PADDING-3 |
+| `Sidebar` | list box, collapsed | PADDING-2 |
+| `Sidebar` | list box, not collapsed | PADDING-3 |
+| `StaticStateRow` | root | PADDING-4 |
+| `Subnav` | root | PADDING-3 |
+| `SurfaceAccordionCard` | accordion body | PADDING-8 |
+| `SurfaceAccordionCard` | accordion body wrapper | PADDING-0 |
+| `SurfaceAccordionCard` | accordion trigger | PADDING-4 |
+| `SurfaceCard` | card content, composition!="joined" | PADDING-4 |
+| `SurfaceCard` | card content, composition="joined" | PADDING-0 |
+| `SurfaceListCard` | root | PADDING-0 |
+| `Tabs` | hero tabs tab | PADDING-3 |
+| `Tabs` | root, inset="page" | PADDING-5 |
+| `TextAction` | root, appearance="choice" | PADDING-1 |
+| `TextAction` | root, appearance="choice" | PADDING-2 |
+| `TextAction` | root, appearance="route" | PADDING-2 |
+| `TextAction` | root, appearance="route" | PADDING-3 |
+| `TextAction` | root, appearance="section" | PADDING-2 |
+| `TextAction` | root, appearance="section" | PADDING-3 |
+| `TextAction` | root, appearance="tab" | PADDING-3 |
+| `Tooltip` | content | PADDING-1 |
+| `Tooltip` | content | PADDING-2 |
+
+## Tiếp xúc theo cạnh
+
+Một ranh giới không phải lúc nào cũng lấy một giá trị cho cả bốn cạnh. Khi một surface để phẳng và
+các dải con tự sở hữu inset của mình, mỗi cạnh lấy giá trị theo thứ mà nó chạm vào.
+
+| Cạnh chạm vào | Giá trị | Rule |
+| --- | --- | --- |
+| Mép ngoài của surface | `1rem` | PADDING-4 |
+| Separator giữa hai dải | `.75rem` | PADDING-3 |
+| Không chạm gì, vì con đã sở hữu mép | `0` | PADDING-0 |
+
+Separator đã tự vẽ ra đường ranh, nên cạnh chạm vào nó cần ít khoảng hở hơn cạnh chạm mép trần. Hai
+cạnh ngang của một dải luôn chạm mép ngoài, nên luôn giữ `1rem`.
+
+Với một chồng dải thì quy ra `px-4` xuyên suốt, `pt-4` ở dải đầu, `pb-4` ở dải cuối, và `.75rem` cho
+mọi cạnh chạm separator. Một dải nằm giữa hai separator là `px-4 py-3`.
+
+Common sở hữu bản thân cái surface phẳng qua `composition="joined"`, thứ đặt inset nội dung về `0`.
+Nó chưa có đường nào cho inset của các dải, nên phần đó vẫn là workaround của ứng dụng.
+
+## PADDING-0 — `p-0` / `0`
+
+Ranh giới không đóng góp khoảng cách nào, vì nội dung hoặc phần tử con đã tự mang đường bao của nó.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Container chỉ gom nhóm, mà mỗi con đã tự mang ranh giới riêng | `App` | `<section className="p-0">` |
+| Case 2 | Các dải trong surface phải chạy sát mép card | `SurfaceCard` | `composition="joined"` đã đặt sẵn `0` |
+| Case 3 | Danh sách mà mỗi hàng tự sở hữu inset của nó | `SurfaceListCard` | Ghép card, không viết padding |
+
+Không phải rule này: ranh giới duy nhất bảo vệ nội dung đọc được thì phải giữ inset. Dùng PADDING-4.
+
+## PADDING-1 — `p-1` / `.25rem`
+
+Inset đều nhỏ nhất, dành cho một container cố ý làm nhỏ mà nội dung gần như lấp đầy.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một nhãn hoặc chú giải nhỏ nổi trên canvas do app sở hữu | `App` | `<aside className="p-1">` với `<Text size="xs">` |
+| Case 2 | Vùng cuộn cần chừa chỗ để focus ring không bị cắt | `HorizontalScrollRegion` | Ghép region, không viết padding |
+| Case 3 | Một gợi ý ngắn gắn vào một control | `Tooltip` | Ghép tooltip, không viết padding |
+
+## PADDING-2 — `p-2` / `.5rem`
+
+Container nhỏ gọn do app sở hữu, cần khoảng mép rõ ràng nhưng tiết kiệm.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một dải phụ nhỏ mà cả bốn cạnh dùng chung một inset | `App` | `<aside className="p-2">` với `<Text size="sm">` |
+| Case 2 | Một thanh control gọn nằm trên nội dung do app sở hữu | `App` | `<div className="flex items-center gap-2 p-2">` |
+
+Không phải rule này: khoảng cách giữa các phần tử con bên trong container thuộc về gap của cha, không
+thuộc padding. Dùng rule GAP tương ứng.
+
+## PADDING-3 — `p-3` / `.75rem`
+
+Inset dày dặn nhưng vẫn đọc được, cho một section hoặc container lồng do app sở hữu.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một container lồng bên trong, sở hữu ranh giới khác với ranh giới của cha | `App` | `<aside className="p-3">` nằm trong section `p-4` |
+| Case 2 | Inset ngang của một thanh tab hoặc navigation phụ | `Tabs`, `Subnav` | Ghép component, không viết padding |
+| Case 3 | Cạnh của một dải chạm separator bên trong surface phẳng | `—` | `<div className="px-4 py-3">` nằm giữa hai separator |
+| Case 4 | Cạnh hướng về separator của một ô metric hoặc một hàng danh sách | `—` | `<div className="p-4 pb-3">`, hoặc `pt-3` khi separator nằm trên |
+
+Không phải rule này: lồng cùng một inset cho cùng một ranh giới và cùng mục đích là nhân đôi nó.
+Padding của cha và của con cộng dồn trên đường từ mép ngoài tới nội dung cuối.
+
+## PADDING-4 — `p-4` / `1rem`
+
+Inset đều chuẩn cho nội dung đọc được bên trong một ranh giới do app sở hữu.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một section của app sở hữu trọn khoảng cách từ đường viền tới nội dung | `App` | `<section className="p-4">` với `<Heading level={2}>` |
+| Case 2 | Nội dung bên trong một card | `SurfaceCard` | Ghép card, không viết padding |
+| Case 3 | Trigger của disclosure và panel xổ ra của nó | `SurfaceAccordionCard` | Ghép card, không viết padding |
+| Case 4 | Một thông báo trạng thái rỗng | `EmptyNotice` | Ghép notice, không viết padding |
+| Case 5 | Một khối code có khung | `FencedCodeBlock` | Ghép khối, không viết padding |
+| Case 6 | Cạnh của một dải chạm mép ngoài của surface phẳng | `—` | `pt-4` ở dải đầu, `pb-4` ở dải cuối |
+| Case 7 | Hai cạnh ngang của mọi dải bên trong surface phẳng | `—` | `px-4` cho mọi dải, không đổi theo vị trí |
+
+## PADDING-5 — `p-6` / `1.5rem`
+
+Một section lớn do app sở hữu, cố ý thoáng hơn mức inset chuẩn.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Section mà cả bốn cạnh dùng chung một quyết định ranh giới rộng rãi | `App` | `<section className="p-6">` |
+| Case 2 | Khung tab mang inset ngang ở cấp trang | `Tabs` | `inset="page"` đã đặt sẵn `1.5rem` |
+
+Không phải rule này: khoảng cách giữa các section con là gap chứ không phải inset. Dùng GAP-5.
+
+## PADDING-6 — `p-8` / `2rem`
+
+Một khung rộng rãi có chủ ý bao quanh vùng lớn, mật độ thấp.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Vùng trang cần khoảng trống đều và mạnh ở mọi cạnh | `App` | `<section className="p-8">` |
+| Case 2 | Vùng rỗng hoặc đang chờ, chiếm gần hết viewport | `App` | `<section className="p-8">` với `<EmptyNotice>` |
+
+Không phải rule này: lấy làm mặc định cho container thường là phí viewport. Dùng PADDING-4.
+
+## Inset ghép
+
+`PADDING-0` tới `PADDING-6` là thang: một rule, một giá trị. Từ `PADDING-7` trở đi, rule là những
+công thức có tên mà các cạnh cố ý lấy giá trị khác nhau. Số vẫn đếm tiếp, nhưng thôi mang nghĩa vị
+trí trên thang, nên một rule ghép không bao giờ xuất hiện trong bảng thang và không tự đẻ ra giá trị
+mới. Mọi cạnh của một công thức ghép đều quy về một rule gốc.
+
+Thêm số tiếp theo khi xuất hiện một pattern lệch cạnh thật sự mới. Phải nêu lý do vì sao từng cạnh
+khác nhau; một công thức không có lý do thì là quyết định riêng của sản phẩm chứ không phải rule.
+
+## PADDING-7 — Nhích inset lên ở breakpoint rộng
+
+Cùng một ranh giới giữ nguyên ý nghĩa qua các khổ màn hình nhưng lấy rộng hơn khi có chỗ. Giá trị ở
+khổ hẹp và khổ rộng là hai rule liền kề, không bao giờ nhảy hai bậc, và trục block chỉ nhích theo ở
+những cạnh mà chính ranh giới đó làm chủ.
+
+Ghép từ: hai cạnh ngang của surface `1rem` → `1.5rem` (PADDING-4 → PADDING-5); cạnh trục block chạm
+mép ngoài `1rem` → `1.5rem` (PADDING-4 → PADDING-5); cạnh trục block chạm separator giữ `.75rem` ở cả
+hai khổ (PADDING-3).
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một surface quyết định, inset ngang mở rộng ra ở viewport lớn hơn | `—` | `<div className="px-4 sm:px-6">` |
+| Case 2 | Cạnh trục block chạm mép ngoài của chính surface đó, nhích theo cùng | `—` | `<div className="px-4 pt-4 pb-4 sm:px-6 sm:pt-6 sm:pb-6">` |
+| Case 3 | Cạnh hướng về separator bên trong surface đó | `—` | `pt-3` giữ `.75rem` ở cả hai khổ |
+
+Không phải rule này: cạnh chạm separator thì không nhích, vì separator vẫn vẽ đúng một đường ở mọi
+khổ màn hình.
+
+## PADDING-8 — Nội dung con thụt vào ở đầu trục inline
+
+Nội dung thuộc về hàng nằm trên nó, chứ không phải đứng ngang với nó, thì thụt vào một bậc ở đầu
+trục inline. Chỉ cạnh đầu mang nghĩa phân cấp. Cạnh cuối không mang nghĩa đó nên giữ thẳng hàng với
+cha, và khổ đọc không bị bóp từ cả hai phía.
+
+Ghép từ: đầu trục inline cao hơn inset của surface một bậc, `1.5rem` khi surface là `1rem`
+(PADDING-5); cuối trục inline đúng inset của surface, giữ nguyên (PADDING-4); hai cạnh trục block theo
+thứ mà cạnh đó chạm, dùng luật tiếp xúc (PADDING-3, PADDING-4).
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Phần thân disclosure, đọc lên là câu trả lời thuộc về trigger phía trên | `—` | `<div className="ps-6 pe-4 py-3">` |
+| Case 2 | Một nhóm lồng mà các hàng thuộc về một hàng cha có tên | `—` | Cùng công thức, mỗi cấp lồng thêm một bậc |
+
+Không phải rule này: thụt vào cả hai bên, vì như vậy là canh giữa nội dung và đọc lên thành một khối
+inset riêng chứ không phải nội dung con.
+
+Disclosure của Common hiện áp `1rem` cho cả hai cạnh ngang, nên dạng thụt vào chưa có đường công
+khai. Việc sửa thuộc về chính component disclosure, không phải một override ở tầng ứng dụng.
+
+## PADDING-9 — Inset trục dọc của một block được route ở breakpoint rộng
+
+Một block được route tự cho `main` của nó một inset dọc, nhích lên khi chiều rộng cho phép, còn
+inset trục ngang vẫn thuộc `PageContainer` (`--grammar-page-inset`). Hai giá trị là hai rule kề nhau
+trên thang, không bao giờ nhảy hai bậc, và ở đây chỉ viết trục dọc.
+
+Ghép từ: hai cạnh trục dọc của block được route `1.5rem` → `2rem` (PADDING-5 → PADDING-6); trục ngang
+không có, vì `PageContainer` sở hữu (MEASURE-1).
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | `main` của một block được route nằm ngay dưới shell của trang | `App` | `<main className="py-6 sm:py-8">` |
+
+Bằng chứng, bốn block viết cùng một cặp: `blocks/commerce/ProSubscriptionBlock/classNames.ts`
+(`proPageClassName`), `blocks/learn/CoursePlaygroundCatalog/classNames.ts`,
+`blocks/learn/PlaygroundSession/classNames.ts`, `blocks/learn/PlaygroundSetup/classNames.ts`.
+
+Không phải rule này: inset trục ngang trên cùng phần tử, vì nó lặp lại inset trang mà container đã
+vẽ. Dùng MEASURE-1 và để yên trục ngang.
+
+## Biến thể theo trục
+
+`px-*` và `py-*` không phải rule riêng. Chúng áp một rule đã có lên một trục, khi hai trục mang hai
+quyết định ranh giới khác nhau.
+
+| Trục | Class | Nghĩa |
+| --- | --- | --- |
+| Inline | `px-*` | Rule đã chọn chỉ áp cho cạnh đầu và cuối theo chiều ngang |
+| Block | `py-*` | Rule đã chọn chỉ áp cho cạnh trên và dưới |
+| Một cạnh | `pt-*`, `pb-*`, `ps-*`, `pe-*` | Rule đã chọn chỉ áp cho đúng cạnh đó |
+
+Class theo từng cạnh chính là thứ luật tiếp xúc cần đến, vì hai cạnh trục block của cùng một dải
+thường lấy hai giá trị khác nhau. `px-4 pt-4 pb-3` là PADDING-4 ở ba cạnh và PADDING-3 ở cạnh chạm
+separator, và mỗi cạnh vẫn phải gọi tên case của riêng nó.
+
+Trên cùng một phần tử, class hẹp hơn thắng ở những cạnh nó gọi tên chứ không cộng vào nhau, nên
+`p-4 pb-3` cho ra `1rem` ở ba cạnh và `.75rem` ở cạnh dưới. Giữa hai phần tử lồng nhau thì padding
+cộng dồn, và đó là lý do một wrapper thêm vào chỉ để sửa một cạnh lại tạo ra inset không ai muốn.
+
+## 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 lệch ra ngoài thuộc về
+[Margin](margin.md). Page inset thuộc về `PageContainer` và không phải quyết định của ứng dụng.

package/knowledge/ui/presentation/surface.md

@@ -0,0 +1,166 @@
+# Surface presentation
+
+This file answers one question: given a region the application already decided to render, which
+semantic surface token does that region take, and which foreground token pairs with it?
+
+A surface and its foreground always travel together. The application never picks a background alone,
+because a background chosen without its paired foreground leaves the copy on top of it unmeasured,
+which is a contrast defect rather than a preference. Paint inside a Grammar object belongs to
+Grammar; this file resolves only the faces the application owns.
+
+## Catalog
+
+Surfaces have no value ramp, so the rule ID is an address over semantic faces rather than a position
+on a scale. Prefer the earliest rule that works: no surface before the card face, the card face
+before a secondary band, a neutral band before a meaningful one.
+
+| Rule | Surface | Paired foreground | Carries |
+| --- | --- | --- | --- |
+| SURFACE-1 | none, transparent | inherited | Content that already sits on someone else's face |
+| SURFACE-2 | `--surface` | `--surface-foreground` | The face of one bounded object |
+| SURFACE-3 | `--surface-secondary` | `--foreground` | A neutral band inside a joined surface |
+| SURFACE-4 | `--accent-soft` | `--accent-soft-foreground` | A band the product deliberately raises |
+| SURFACE-5 | `--success-soft` | the foreground of the band it replaces | A proven outcome |
+| SURFACE-6 | `--accent` | none, because it carries no copy | A decorative slab |
+
+`--surface`, `--surface-secondary` and `--accent` are base theme tokens; `--accent-soft` and
+`--success-soft` and their `-foreground` partners are derived from `--accent` and `--success` on the
+same element, so overriding a base moves the whole family. Nothing on this list may be reproduced as
+a hex value, an `oklch()` literal, or a palette step, even when the literal matches the token.
+
+## Owner
+
+Each case names who owns the face. The owner decides whether the application writes a class at all.
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The region belongs to the application | The class pair |
+| A component name | Grammar already paints this face | Nothing. Pass the prop |
+| `—` | Grammar exposes no public path for this face | The class pair, 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`. Reaching into a Grammar component with a selector
+or a passed class to repaint it is `APP_OVERRIDE`.
+
+## Surfaces 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 | SURFACE-2 |
+| `ChatWorkspace` | rail trigger, hasRail, isCompactRail | SURFACE-2 |
+| `IconTile` | root, not (isSkeleton || showsArtwork), tone="accent" | SURFACE-4 |
+| `IconTile` | root, not (isSkeleton || showsArtwork), tone="success" | SURFACE-5 |
+| `MediaFrame` | root, treatment!="plain" | SURFACE-3 |
+| `MediaFrame` | root, treatment="plain" | SURFACE-1 |
+| `Sidebar` | list box item | SURFACE-4 |
+| `SurfaceAccordionCard` | accordion shell, bounded | SURFACE-2 |
+| `SurfaceAccordionCard` | accordion shell, not bounded | SURFACE-1 |
+| `SurfaceCard` | card content, frame!="frameless" | SURFACE-2 |
+| `SurfaceCard` | card content, frame="frameless" | SURFACE-1 |
+| `SurfaceCard` | root, wholeAction!=undefined | SURFACE-4 |
+| `SurfaceListCard` | root | SURFACE-2 |
+| `TextAction` | root, isCurrent, appearance="choice"|"route"|"section" | SURFACE-4 |
+
+## SURFACE-1 — no surface / inherited foreground
+
+The region paints nothing, because the face underneath it is already the right one and the copy
+inherits the foreground that was measured against it.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Content whose visible boundaries are already drawn by its children | `SurfaceCard` | `frame="frameless"` already sets transparent and `color: inherit` |
+| Case 2 | Media that must sit on the page canvas with no inset frame | `MediaFrame` | `treatment="plain"` already clears the fill and the border |
+| Case 3 | An app-owned grouping container that only stacks children which each own a face | `App` | `<div className="flex min-w-0 flex-col">` with no background class |
+
+Not this rule: a region that needs its own readable face uses SURFACE-2.
+
+## SURFACE-2 — `bg-surface` / `text-surface-foreground`
+
+The face of one bounded object. This is the surface a card presents to the page, and Grammar paints
+it as a pair so the copy inside never has to state a colour.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | One bounded content object on the page canvas | `SurfaceCard` | Compose the card; no background class |
+| Case 2 | A list or disclosure presenting the same bounded face | `SurfaceListCard`, `SurfaceAccordionCard` | Compose the card; no background class |
+| Case 3 | Rows that must show the card face through a joined list at reduced alpha | `—` | `<li className="bg-surface/90">` inside a joined card body |
+
+Not this rule: a band that must read as recessed against the card face uses SURFACE-3.
+
+Case 3 composes two layers, so contrast is measured against the resulting pixels rather than against
+`--surface` alone.
+
+## SURFACE-3 — `bg-surface-secondary` / `text-foreground`
+
+A neutral band inside a joined surface. It reads as recessed against the card face without claiming
+any meaning of its own, so the copy on it stays at ordinary reading attention.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A summary or explanatory band running edge to edge inside a joined card | `—` | `<div className="bg-surface-secondary px-4 py-3 text-foreground">` |
+| Case 2 | A full-bleed illustration band sharing that neutral face | `—` | `<div className="min-w-0 bg-surface-secondary">` with the image inside |
+| Case 3 | The recessed backdrop behind framed media | `MediaFrame` | Compose the frame; no background class |
+
+Not this rule: a band the product means to raise uses SURFACE-4, and a band reporting a proven
+outcome uses SURFACE-5.
+
+The theme also publishes `--surface-secondary-foreground`, but the bands above pair the secondary
+face with `--foreground`. The two resolve to the same value in both themes, so the pair is recorded
+as it is written rather than corrected here.
+
+## SURFACE-4 — `bg-accent-soft` / `text-accent-soft-foreground`
+
+A band the product deliberately raises. Accent is scarce: repeated across every peer band it stops
+marking anything, and the raised band still has to say in words why it is raised.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | One summary band inside a joined card that the product ranked above its peers | `—` | `<div className="bg-accent-soft px-4 py-3 text-accent-soft-foreground">` |
+| Case 2 | A leading marker inside a raised region, taking the paired foreground alone | `—` | `<Icon className="text-accent-soft-foreground" />` on the raised band |
+| Case 3 | A card whose whole face responds to hover or keyboard focus | `SurfaceCard` | `interaction="whole-action"` already swaps the face |
+
+Not this rule: a full-strength accent slab under copy. Use SURFACE-6 only where no copy sits on it.
+
+A raised band that omits `text-accent-soft-foreground` leaves its copy on the inherited foreground of
+whatever face it replaced, which is the defect this rule exists to prevent.
+
+`--accent-soft` is a `color-mix` of `--accent` toward transparent, so the band is translucent and the
+face beneath it shows through. Contrast on this rule is therefore measured against the composed
+pixels, never against the token.
+
+## SURFACE-5 — `bg-success-soft` / the foreground of the band it replaces
+
+A band reports a proven outcome by exchanging its neutral face for the status face, and keeps the
+foreground the neutral band already established.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A band whose outcome is settled and evidenced, not merely promised | `—` | The neutral band class followed by `bg-success-soft` |
+| Case 2 | The same band before the outcome is proven | `—` | Stay on SURFACE-3; do not pre-paint the result |
+
+Not this rule: colour as the only carrier of the outcome. The band still states the outcome in words,
+and status colour is never chosen as a text tone.
+
+The status face is exchanged without a matching foreground swap, so the pair is `--success-soft` under
+`--foreground`. That composition has to be measured, not assumed, in both themes.
+
+## SURFACE-6 — `bg-accent` / no paired foreground
+
+A decorative slab at full accent strength. It is admissible only because nothing readable sits on it,
+which is also why it names no foreground.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A hero band carrying one decorative image and no copy | `—` | `<div className="relative isolate min-h-32 overflow-hidden bg-accent">` with an `aria-hidden` image |
+
+Not this rule: any slab carrying text, a label, or a control. Put copy on SURFACE-4 instead, where a
+paired foreground exists.
+
+## What this file does not decide
+
+Which foreground a single line of copy takes, once its surface is settled, is [Tone](tone.md). The
+edges that separate two faces are [Boundary](boundary.md). The space between a face and its content
+is [Padding](padding.md), and the clipping that keeps a band inside its card is
+[Overflow](overflow.md).

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

@@ -0,0 +1,166 @@
+# Surface presentation
+
+File này trả lời đúng một câu hỏi: một vùng mà ứng dụng đã quyết định render thì nhận token surface
+ngữ nghĩa nào, và token foreground nào đi kèm với nó.
+
+Surface và foreground luôn đi thành cặp. Ứng dụng không bao giờ chọn riêng phần nền, vì một nền chọn
+mà thiếu foreground đi kèm sẽ để phần copy nằm trên đó không được đo, và đó là lỗi tương phản chứ
+không phải chuyện sở thích. Phần sơn bên trong một Grammar object thuộc về Grammar; file này chỉ giải
+quyết những mặt do ứng dụng sở hữu.
+
+## Danh mục
+
+Surface không có thang giá trị, nên số của rule là địa chỉ trên tập các mặt ngữ nghĩa 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: không surface trước mặt card, mặt card
+trước dải phụ, dải trung tính trước dải mang nghĩa.
+
+| Rule | Surface | Foreground đi kèm | Mang nghĩa |
+| --- | --- | --- | --- |
+| SURFACE-1 | không có, trong suốt | kế thừa | Nội dung đã nằm trên mặt của người khác |
+| SURFACE-2 | `--surface` | `--surface-foreground` | Mặt của một đối tượng có ranh giới |
+| SURFACE-3 | `--surface-secondary` | `--foreground` | Dải trung tính bên trong một surface nối liền |
+| SURFACE-4 | `--accent-soft` | `--accent-soft-foreground` | Dải mà sản phẩm cố ý nâng lên |
+| SURFACE-5 | `--success-soft` | foreground của dải mà nó thay thế | Một kết quả đã được chứng minh |
+| SURFACE-6 | `--accent` | không có, vì không có copy nằm trên | Một mảng trang trí |
+
+`--surface`, `--surface-secondary` và `--accent` là token nền của theme; `--accent-soft`,
+`--success-soft` cùng các bản `-foreground` của chúng được dẫn xuất từ `--accent` và `--success` trên
+cùng một element, nên ghi đè token gốc là dịch cả họ. Không token nào trong danh sách này được viết
+lại bằng giá trị hex, literal `oklch()`, hay một bậc palette, kể cả khi literal đó trùng giá trị.
+
+## Owner
+
+Mỗi case gọi tên ai sở hữu cái mặt đó. Owner quyết định ứng dụng có được viết class hay không.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Vùng thuộc về ứng dụng | Viết cặp class |
+| Tên component | Grammar đã sơn mặt này | Không viết gì, chỉ truyền prop |
+| `—` | Grammar chưa có đường dùng công khai cho mặt này | Viết cặp 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ò vào một Grammar component bằng selector hay class
+truyền xuống để sơn lại nó là `APP_OVERRIDE`.
+
+## Surface 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 | SURFACE-2 |
+| `ChatWorkspace` | rail trigger, hasRail, isCompactRail | SURFACE-2 |
+| `IconTile` | root, not (isSkeleton || showsArtwork), tone="accent" | SURFACE-4 |
+| `IconTile` | root, not (isSkeleton || showsArtwork), tone="success" | SURFACE-5 |
+| `MediaFrame` | root, treatment!="plain" | SURFACE-3 |
+| `MediaFrame` | root, treatment="plain" | SURFACE-1 |
+| `Sidebar` | list box item | SURFACE-4 |
+| `SurfaceAccordionCard` | accordion shell, bounded | SURFACE-2 |
+| `SurfaceAccordionCard` | accordion shell, not bounded | SURFACE-1 |
+| `SurfaceCard` | card content, frame!="frameless" | SURFACE-2 |
+| `SurfaceCard` | card content, frame="frameless" | SURFACE-1 |
+| `SurfaceCard` | root, wholeAction!=undefined | SURFACE-4 |
+| `SurfaceListCard` | root | SURFACE-2 |
+| `TextAction` | root, isCurrent, appearance="choice"|"route"|"section" | SURFACE-4 |
+
+## SURFACE-1 — không có surface / foreground kế thừa
+
+Vùng không sơn gì cả, vì cái mặt bên dưới nó đã đúng rồi và phần copy kế thừa đúng foreground đã được
+đo trên mặt đó.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Nội dung mà các ranh giới nhìn thấy được đã do chính con của nó vẽ | `SurfaceCard` | `frame="frameless"` đã đặt sẵn trong suốt và `color: inherit` |
+| Case 2 | Media phải nằm thẳng trên canvas trang, không khung lót | `MediaFrame` | `treatment="plain"` đã bỏ sẵn phần nền và border |
+| Case 3 | Container gom nhóm do app sở hữu, chỉ xếp chồng các con mà mỗi con tự có mặt riêng | `App` | `<div className="flex min-w-0 flex-col">` không có class nền |
+
+Không phải rule này: một vùng cần mặt đọc được của riêng nó thì dùng SURFACE-2.
+
+## SURFACE-2 — `bg-surface` / `text-surface-foreground`
+
+Mặt của một đối tượng có ranh giới. Đây là mặt mà một card trình ra với trang, và Grammar sơn nó theo
+cặp để phần copy bên trong không bao giờ phải tự khai màu.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một đối tượng nội dung có ranh giới nằm trên canvas trang | `SurfaceCard` | Ghép card, không viết class nền |
+| Case 2 | Một list hay disclosure trình ra cùng cái mặt có ranh giới đó | `SurfaceListCard`, `SurfaceAccordionCard` | Ghép card, không viết class nền |
+| Case 3 | Các hàng phải để lộ mặt card qua một list nối liền ở độ trong nhất định | `—` | `<li className="bg-surface/90">` bên trong thân card nối liền |
+
+Không phải rule này: một dải cần đọc thành lõm xuống so với mặt card thì dùng SURFACE-3.
+
+Case 3 chồng hai lớp lên nhau, nên tương phản được đo trên pixel kết quả chứ không phải trên riêng
+`--surface`.
+
+## SURFACE-3 — `bg-surface-secondary` / `text-foreground`
+
+Dải trung tính bên trong một surface nối liền. Nó đọc thành lõm xuống so với mặt card mà không tự
+nhận nghĩa nào, nên phần copy trên đó vẫn ở mức chú ý đọc bình thường.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Dải tóm tắt hoặc diễn giải chạy sát hai mép trong một card nối liền | `—` | `<div className="bg-surface-secondary px-4 py-3 text-foreground">` |
+| Case 2 | Dải minh hoạ tràn viền dùng chung cái mặt trung tính đó | `—` | `<div className="min-w-0 bg-surface-secondary">` với ảnh bên trong |
+| Case 3 | Nền lõm phía sau media có khung | `MediaFrame` | Ghép frame, không viết class nền |
+
+Không phải rule này: dải mà sản phẩm cố ý nâng lên thì dùng SURFACE-4, còn dải báo một kết quả đã
+chứng minh thì dùng SURFACE-5.
+
+Theme cũng công bố `--surface-secondary-foreground`, nhưng các dải ở trên ghép mặt phụ với
+`--foreground`. Hai token này quy về cùng một giá trị ở cả hai theme, nên cặp này được ghi đúng như nó
+đang được viết chứ không sửa lại ở đây.
+
+## SURFACE-4 — `bg-accent-soft` / `text-accent-soft-foreground`
+
+Một dải mà sản phẩm cố ý nâng lên. Accent là thứ khan hiếm: lặp lại trên mọi dải ngang hàng thì nó
+thôi đánh dấu điều gì, và dải được nâng vẫn phải nói bằng chữ vì sao nó được nâng.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một dải tóm tắt trong card nối liền mà sản phẩm đã xếp trên các dải ngang hàng | `—` | `<div className="bg-accent-soft px-4 py-3 text-accent-soft-foreground">` |
+| Case 2 | Một dấu dẫn đầu bên trong vùng được nâng, chỉ lấy riêng foreground đi kèm | `—` | `<Icon className="text-accent-soft-foreground" />` trên dải được nâng |
+| Case 3 | Một card mà cả mặt của nó phản hồi khi hover hoặc focus bàn phím | `SurfaceCard` | `interaction="whole-action"` đã đổi sẵn cái mặt |
+
+Không phải rule này: một mảng accent nguyên độ nằm dưới copy. Chỉ dùng SURFACE-6 ở chỗ không có copy
+nào nằm trên.
+
+Một dải được nâng mà bỏ `text-accent-soft-foreground` sẽ để copy của nó nằm trên foreground kế thừa
+của cái mặt mà nó vừa thay, và đó chính là lỗi mà rule này sinh ra để chặn.
+
+`--accent-soft` là một `color-mix` của `--accent` pha về phía trong suốt, nên dải này không đục và mặt
+bên dưới vẫn lộ qua. Vì vậy tương phản ở rule này được đo trên pixel đã chồng, không bao giờ đo trên
+token.
+
+## SURFACE-5 — `bg-success-soft` / foreground của dải mà nó thay thế
+
+Một dải báo kết quả đã được chứng minh bằng cách đổi mặt trung tính của nó lấy mặt trạng thái, và giữ
+nguyên foreground mà dải trung tính đã thiết lập.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Dải mà kết quả đã ngã ngũ và có bằng chứng, không phải mới chỉ hứa | `—` | Class dải trung tính rồi tới `bg-success-soft` |
+| Case 2 | Chính dải đó khi kết quả chưa được chứng minh | `—` | Ở lại SURFACE-3, không sơn trước kết quả |
+
+Không phải rule này: lấy màu làm phương tiện duy nhất chở kết quả. Dải vẫn phải nói kết quả bằng chữ,
+và màu trạng thái không bao giờ được chọn như một tone chữ.
+
+Mặt trạng thái được đổi mà không đổi foreground kèm theo, nên cặp thực tế là `--success-soft` dưới
+`--foreground`. Tổ hợp đó phải được đo ở cả hai theme, không được suy đoán.
+
+## SURFACE-6 — `bg-accent` / không có foreground đi kèm
+
+Một mảng trang trí ở độ accent nguyên. Nó chỉ được chấp nhận vì không có gì đọc được nằm trên đó, và
+cũng chính vì thế nó không gọi tên foreground nào.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Dải hero chỉ mang một ảnh trang trí và không mang copy | `—` | `<div className="relative isolate min-h-32 overflow-hidden bg-accent">` với một ảnh `aria-hidden` |
+
+Không phải rule này: bất kỳ mảng nào mang chữ, nhãn hay control. Đặt copy lên SURFACE-4, nơi có sẵn
+một foreground đi kèm.
+
+## File này không quyết định
+
+Một dòng copy lấy foreground nào sau khi surface của nó đã chốt là việc của [Tone](tone.md). Các cạnh
+tách hai mặt là [Boundary](boundary.md). Khoảng cách giữa một mặt và nội dung của nó là
+[Padding](padding.md), còn việc cắt để giữ một dải nằm gọn trong card là [Overflow](overflow.md).