@starci/skills 1.1.0

package/knowledge/ui/presentation/gap.md

@@ -0,0 +1,181 @@
+# Gap presentation
+
+This file answers one question: given a container the application already decided to render, which
+gap value does it get?
+
+Composition has already chosen the DOM tree, the flex or grid direction, and the Grammar objects. Gap
+presentation resolves only the distance between those objects, and only where the application owns
+the container. Distances inside a Grammar object belong to Grammar.
+
+## Scale
+
+`COMMON_SPACING_SCALE` is closed. The rule ID is the ordinal position on that scale. It is not the
+Tailwind step number, and the two diverge from GAP-5 onward.
+
+| Rule | Class | Value | Common token |
+| --- | --- | --- | --- |
+| GAP-0 | `gap-0` | `0` | none |
+| GAP-1 | `gap-1` | `.25rem` | none |
+| GAP-2 | `gap-2` | `.5rem` | `--grammar-inline-gap` |
+| GAP-3 | `gap-3` | `.75rem` | `--grammar-row-gap` |
+| GAP-4 | `gap-4` | `1rem` | `--grammar-section-gap` |
+| GAP-5 | `gap-6` | `1.5rem` | `--grammar-region-gap` |
+| GAP-6 | `gap-8` | `2rem` | none |
+
+The rem values resolve to `0 / 4 / 8 / 12 / 16 / 24 / 32` CSS pixels only at a computed root of
+`16px`. Runtime checks use `expectedPx = remFactor * observedRootFontPx`.
+
+## Owner
+
+Each case names who owns the distance. The owner decides whether the application writes a class at
+all.
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The container belongs to the application | The class |
+| A component name | Common already applies the gap inside that component | Nothing. Pass the prop |
+| `—` | Common exposes no public path for this relationship | 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`.
+
+## Gaps 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` | layout | GAP-5 |
+| `Divider` | root | GAP-3 |
+| `EmptyNotice` | root | GAP-3 |
+| `Input` | root | GAP-2 |
+| `MediaFrame` | root | GAP-2 |
+| `NavigationFeatureNav` | actions, actions!=undefined | GAP-2 |
+| `NavigationFeatureNav` | primary | GAP-3 |
+| `PrimaryRailLayout` | root | GAP-5 |
+| `Rail` | frame | GAP-4 |
+| `SectionHeader` | copy | GAP-2 |
+| `SectionHeader` | root | GAP-5 |
+| `Sidebar` | list box | GAP-1 |
+| `Sidebar` | list box item, not collapsed | GAP-3 |
+| `Sidebar` | list box section | GAP-1 |
+| `StaticStateRow` | root | GAP-3 |
+| `StaticStateRow` | row copy | GAP-1 |
+| `Subnav` | identity | GAP-2 |
+| `Subnav` | root | GAP-3 |
+| `SurfaceAccordionCard` | label, label!=undefined | GAP-2 |
+| `SurfaceCard` | card content, composition="joined" | GAP-0 |
+| `SurfaceCard` | label, label!=undefined | GAP-2 |
+| `SurfaceCopyGroup` | root, density!="comfortable" | GAP-2 |
+| `SurfaceCopyGroup` | root, density="comfortable" | GAP-3 |
+| `SurfaceListCard` | label, not (label === undefined || labelHidden) | GAP-2 |
+| `Tabs` | tab content | GAP-2 |
+| `Text` | root, not isSkeleton, showsStartContent | GAP-2 |
+| `TextAction` | root | GAP-2 |
+| `WorkspaceShell` | layout | GAP-5 |
+| `WorkspaceShell` | primary | GAP-5 |
+
+## GAP-0 — `gap-0` / `0`
+
+Adjacent faces meet with no space because another element already owns the seam.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Stacked bands whose boundary is drawn by a separator | `App` | `<div className="flex flex-col gap-0">` with `<Divider />` between bands |
+| Case 2 | A list whose rows are separated by a border, not by space | `SurfaceListCard` | Compose the card; no gap |
+| Case 3 | Joined faces inside one surface | `SurfaceCard` | `composition="joined"` already sets `0` |
+
+## GAP-1 — `gap-1` / `.25rem`
+
+Two stacked lines that read as one identity. The second line qualifies the first rather than
+starting a new item.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A title and the short qualifier bound to it, such as a name under its category | `—` | `<div className="flex flex-col gap-1">` with two `<Text>` |
+| Case 2 | A value and the unit or timestamp bound to it | `—` | Same container |
+| Case 3 | The copy pair inside a status row | `StaticStateRow` | Compose the row; no gap |
+
+Not this rule: two separately readable items, even short ones, use GAP-3.
+
+## GAP-2 — `gap-2` / `.5rem`
+
+Inline companions inside one control, or two compact items that act as one unit.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | An icon beside its label inside one control | `Text` | `<Text startContent={<Icon source={check} />}>Active</Text>` |
+| Case 2 | A title with its explanation inside a surface | `SurfaceCopyGroup` | `<SurfaceCopyGroup>` at default density |
+| Case 3 | Two adjacent inline actions in an app-owned row | `App` | `<div className="flex items-center gap-2">` with two `<TextAction>` |
+| Case 4 | A row of badges or short status chips | `App` | `<div className="flex flex-wrap gap-2">` with `<Badge>` children |
+
+## GAP-3 — `gap-3` / `.75rem`
+
+Peer items in one row or one tightly related group. Each item is read on its own, but they belong
+together.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A field and the action that submits it, side by side | `App` | `<div className="flex items-end gap-3">` with `<Input>` and `<Button>` |
+| Case 2 | A title and its explanation that need more air than the compact default | `SurfaceCopyGroup` | `<SurfaceCopyGroup density="comfortable">` |
+| Case 3 | Two peer controls sharing one decision, such as a pair of filters | `App` | `<div className="flex gap-3">` |
+| Case 4 | A section header whose copy and action stack because its container is narrow | `SectionHeader` | Compose the header; no gap |
+
+Not this rule: blocks that each carry their own heading use GAP-4.
+
+## GAP-4 — `gap-4` / `1rem`
+
+Sibling blocks inside one section. Each block is a separate piece of content, but the section still
+reads as one group.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Stacked content blocks under one section heading | `App` | `<section className="flex flex-col gap-4">` |
+| Case 2 | Cards in a grid belonging to one collection | `App` | `<div className="grid grid-cols-2 gap-4">` with `<SurfaceCard>` children |
+| Case 3 | A form's field groups within one step | `App` | `<div className="flex flex-col gap-4">` with `<Input>` children |
+| Case 4 | Prose blocks inside rendered article content | `MarkdownArticle` | Compose the article; no gap |
+
+## GAP-5 — `gap-6` / `1.5rem`
+
+Regions of a page. Each region has its own purpose and its own heading, and the reader moves between
+them rather than through them.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Two page regions with distinct purposes, such as a summary above a history list | `App` | `<main className="flex flex-col gap-6">` with two `<section>` |
+| Case 2 | The standing rhythm between top-level sections of a dashboard | `App` | `<div className="flex flex-col gap-6">` |
+| Case 3 | The primary column beside its rail | `PrimaryRailLayout` | Compose the layout; no gap |
+| Case 4 | Shell regions around routed page content | `WorkspaceShell` | Compose the shell; no gap |
+
+Not this rule: blocks that share one heading and one purpose use GAP-4.
+
+## GAP-6 — `gap-8` / `2rem`
+
+A named major transition. The strongest break the scale offers, used only when the ordinary region
+rhythm fails to separate two parts of the page.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A page whose halves serve unrelated tasks, where `1.5rem` reads as one continuous column | `—` | `<main className="flex flex-col gap-8">` |
+| Case 2 | A marketing surface whose sections are deliberately spacious | `—` | Same container |
+
+Not this rule: applying it to every region uniformly removes hierarchy. Use GAP-5.
+
+## Axis variants
+
+`gap-x-*` and `gap-y-*` are not separate rules. They apply an existing rule to one axis when the two
+axes carry different relationships, most often on a wrapping or grid parent.
+
+| Axis | Class | Meaning |
+| --- | --- | --- |
+| Inline | `gap-x-*` | The chosen rule applies between columns only |
+| Block | `gap-y-*` | The chosen rule applies between rows only |
+
+A wrapping list whose columns are inline companions and whose rows are peers is `gap-x-2 gap-y-3`,
+which is GAP-2 on the inline axis and GAP-3 on the block axis. Each axis names its own case.
+
+## What this file does not decide
+
+Padding inside an app boundary is [Padding](padding.md). External offsets are [Margin](margin.md).
+Which DOM structure, flex direction, or Grammar object to render was decided before this file is
+read, and no gap value can repair a wrong composition.

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

@@ -0,0 +1,181 @@
+# Gap presentation
+
+File này trả lời đúng một câu hỏi: một container mà ứng dụng đã quyết định render thì nhận giá trị
+gap nào.
+
+Bước composition đã chọn xong cây DOM, hướng flex hay grid, và các Grammar object. Gap presentation
+chỉ giải quyết khoảng cách giữa những object đó, và chỉ ở nơi ứng dụng sở hữu container. Khoảng cách
+bên trong một Grammar object 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ừ GAP-5 trở đi.
+
+| Rule | Class | Giá trị | Token Common |
+| --- | --- | --- | --- |
+| GAP-0 | `gap-0` | `0` | không có |
+| GAP-1 | `gap-1` | `.25rem` | không có |
+| GAP-2 | `gap-2` | `.5rem` | `--grammar-inline-gap` |
+| GAP-3 | `gap-3` | `.75rem` | `--grammar-row-gap` |
+| GAP-4 | `gap-4` | `1rem` | `--grammar-section-gap` |
+| GAP-5 | `gap-6` | `1.5rem` | `--grammar-region-gap` |
+| GAP-6 | `gap-8` | `2rem` | không có |
+
+Các giá trị rem chỉ quy ra `0 / 4 / 8 / 12 / 16 / 24 / 32` pixel CSS khi root font size tính được là
+`16px`. Khi kiểm tra lúc chạy thì dùng `expectedPx = remFactor * observedRootFontPx`.
+
+## Owner
+
+Mỗi case gọi tên ai sở hữu khoảng cách. Owner quyết định ứng dụng có được viết class hay không.
+
+| Owner | Nghĩa | Ứng dụng viết |
+| --- | --- | --- |
+| `App` | Container thuộc về ứng dụng | Viết class |
+| Tên component | Common đã áp gap bên trong component đó | Không viết gì, chỉ truyền prop |
+| `—` | Common chưa có đường dùng công khai cho quan hệ này | Viết class, ghi nhận là workaround |
+
+Viết class ở chỗ owner là một component chính là `APP_REIMPLEMENTATION`. Viết class ở chỗ owner là
+`—` thì gắn liền với `COMMON_CAPABILITY_MISSING`.
+
+## Gap 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` | layout | GAP-5 |
+| `Divider` | root | GAP-3 |
+| `EmptyNotice` | root | GAP-3 |
+| `Input` | root | GAP-2 |
+| `MediaFrame` | root | GAP-2 |
+| `NavigationFeatureNav` | actions, actions!=undefined | GAP-2 |
+| `NavigationFeatureNav` | primary | GAP-3 |
+| `PrimaryRailLayout` | root | GAP-5 |
+| `Rail` | frame | GAP-4 |
+| `SectionHeader` | copy | GAP-2 |
+| `SectionHeader` | root | GAP-5 |
+| `Sidebar` | list box | GAP-1 |
+| `Sidebar` | list box item, not collapsed | GAP-3 |
+| `Sidebar` | list box section | GAP-1 |
+| `StaticStateRow` | root | GAP-3 |
+| `StaticStateRow` | row copy | GAP-1 |
+| `Subnav` | identity | GAP-2 |
+| `Subnav` | root | GAP-3 |
+| `SurfaceAccordionCard` | label, label!=undefined | GAP-2 |
+| `SurfaceCard` | card content, composition="joined" | GAP-0 |
+| `SurfaceCard` | label, label!=undefined | GAP-2 |
+| `SurfaceCopyGroup` | root, density!="comfortable" | GAP-2 |
+| `SurfaceCopyGroup` | root, density="comfortable" | GAP-3 |
+| `SurfaceListCard` | label, not (label === undefined || labelHidden) | GAP-2 |
+| `Tabs` | tab content | GAP-2 |
+| `Text` | root, not isSkeleton, showsStartContent | GAP-2 |
+| `TextAction` | root | GAP-2 |
+| `WorkspaceShell` | layout | GAP-5 |
+| `WorkspaceShell` | primary | GAP-5 |
+
+## GAP-0 — `gap-0` / `0`
+
+Hai mặt kề nhau chạm nhau, vì đường ranh đã do một phần tử khác vẽ.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Các dải xếp chồng mà ranh giới do separator vẽ | `App` | `<div className="flex flex-col gap-0">` với `<Divider />` giữa các dải |
+| Case 2 | Danh sách mà các hàng cách nhau bằng border chứ không bằng khoảng trắng | `SurfaceListCard` | Ghép card, không viết gap |
+| Case 3 | Các mặt nối liền bên trong một surface | `SurfaceCard` | `composition="joined"` đã đặt sẵn `0` |
+
+## GAP-1 — `gap-1` / `.25rem`
+
+Hai dòng xếp dọc đọc lên thành một danh tính. Dòng thứ hai bổ nghĩa cho dòng đầu chứ không mở ra một
+mục mới.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một tiêu đề và dòng phụ ngắn thuộc về nó, kiểu tên nằm dưới nhãn phân loại | `—` | `<div className="flex flex-col gap-1">` với hai `<Text>` |
+| Case 2 | Một giá trị và đơn vị hoặc mốc thời gian dính liền với nó | `—` | Cùng container |
+| Case 3 | Cặp copy bên trong một hàng trạng thái | `StaticStateRow` | Ghép hàng, không viết gap |
+
+Không phải rule này: hai mục đọc độc lập được, kể cả khi ngắn, thì dùng GAP-3.
+
+## GAP-2 — `gap-2` / `.5rem`
+
+Những thành phần đi kèm nằm trong cùng một control, hoặc hai mục nhỏ hoạt động như một khối.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một icon nằm cạnh label của nó bên trong một control | `Text` | `<Text startContent={<Icon source={check} />}>Active</Text>` |
+| Case 2 | Một tiêu đề và phần giải thích bên trong một surface | `SurfaceCopyGroup` | `<SurfaceCopyGroup>` với density mặc định |
+| Case 3 | Hai inline action đứng cạnh nhau trong hàng do app sở hữu | `App` | `<div className="flex items-center gap-2">` với hai `<TextAction>` |
+| Case 4 | Một hàng badge hoặc chip trạng thái ngắn | `App` | `<div className="flex flex-wrap gap-2">` với các `<Badge>` |
+
+## GAP-3 — `gap-3` / `.75rem`
+
+Các mục ngang hàng trong một hàng hoặc một nhóm chặt. Mỗi mục đọc riêng được, nhưng chúng thuộc về
+nhau.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Một field và action gửi nó, đặt cạnh nhau | `App` | `<div className="flex items-end gap-3">` với `<Input>` và `<Button>` |
+| Case 2 | Tiêu đề và phần giải thích cần thoáng hơn mức compact mặc định | `SurfaceCopyGroup` | `<SurfaceCopyGroup density="comfortable">` |
+| Case 3 | Hai control ngang hàng phục vụ chung một quyết định, kiểu một cặp bộ lọc | `App` | `<div className="flex gap-3">` |
+| Case 4 | Section header có phần copy và action xếp chồng vì container hẹp | `SectionHeader` | Ghép header, không viết gap |
+
+Không phải rule này: các khối mà mỗi khối tự mang tiêu đề riêng thì dùng GAP-4.
+
+## GAP-4 — `gap-4` / `1rem`
+
+Các khối ngang hàng trong cùng một section. Mỗi khối là một mảng nội dung riêng, nhưng cả section
+vẫn đọc lên thành một nhóm.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Các khối nội dung xếp chồng dưới một tiêu đề section | `App` | `<section className="flex flex-col gap-4">` |
+| Case 2 | Các card trong một lưới cùng thuộc một tập hợp | `App` | `<div className="grid grid-cols-2 gap-4">` với các `<SurfaceCard>` |
+| Case 3 | Các nhóm field của một form trong cùng một bước | `App` | `<div className="flex flex-col gap-4">` với các `<Input>` |
+| Case 4 | Các khối văn bản bên trong nội dung article đã render | `MarkdownArticle` | Ghép article, không viết gap |
+
+## GAP-5 — `gap-6` / `1.5rem`
+
+Các vùng của một trang. Mỗi vùng có mục đích riêng và tiêu đề riêng, người đọc nhảy giữa các vùng chứ
+không đọc xuyên qua.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Hai vùng trang khác mục đích, kiểu phần tóm tắt nằm trên danh sách lịch sử | `App` | `<main className="flex flex-col gap-6">` với hai `<section>` |
+| Case 2 | Nhịp thường trực giữa các section cấp cao nhất của một dashboard | `App` | `<div className="flex flex-col gap-6">` |
+| Case 3 | Cột chính đặt cạnh rail của nó | `PrimaryRailLayout` | Ghép layout, không viết gap |
+| Case 4 | Các vùng shell bao quanh nội dung trang được route | `WorkspaceShell` | Ghép shell, không viết gap |
+
+Không phải rule này: các khối chung một tiêu đề và một mục đích thì dùng GAP-4.
+
+## GAP-6 — `gap-8` / `2rem`
+
+Một bước chuyển lớn có tên. Đây là mức ngắt mạnh nhất mà thang cung cấp, chỉ dùng khi nhịp vùng
+thông thường không đủ tách hai phần của trang.
+
+| Case | Dùng khi | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | Trang mà hai nửa phục vụ hai việc không liên quan, để `1.5rem` thì đọc thành một cột liền mạch | `—` | `<main className="flex flex-col gap-8">` |
+| Case 2 | Một surface marketing mà các section cố ý để thoáng | `—` | Cùng container |
+
+Không phải rule này: áp đồng loạt cho mọi vùng thì mất hết phân cấp. Dùng GAP-5.
+
+## Biến thể theo trục
+
+`gap-x-*` và `gap-y-*` 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 quan hệ khác nhau, thường gặp trên container wrap hoặc grid.
+
+| Trục | Class | Nghĩa |
+| --- | --- | --- |
+| Inline | `gap-x-*` | Rule đã chọn chỉ áp giữa các cột |
+| Block | `gap-y-*` | Rule đã chọn chỉ áp giữa các hàng |
+
+Một danh sách wrap mà theo chiều ngang là các thành phần đi kèm còn theo chiều dọc là các mục ngang
+hàng thì viết `gap-x-2 gap-y-3`, tức GAP-2 trên trục inline và GAP-3 trên trục block. Mỗi trục vẫn
+phải gọi tên case của riêng nó.
+
+## File này không quyết định
+
+Padding bên trong ranh giới của app thuộc về [Padding](padding.md). Khoảng lệch ra ngoài thuộc về
+[Margin](margin.md). Việc chọn cấu trúc DOM, hướng flex, hay Grammar object nào đã được quyết trước
+khi đọc file này, và không giá trị gap nào cứu được một composition sai.

package/knowledge/ui/presentation/margin.md

@@ -0,0 +1,168 @@
+# Margin presentation
+
+This file answers one question: when may an application-owned object push away from its surroundings
+with an external offset, and how much?
+
+Margin is the exception in this system, not the default. A distance between siblings belongs to the
+parent's gap, and a distance from a boundary to its content belongs to that boundary's padding.
+Margin is correct only when one object needs an offset that no parent relationship can express, and
+that reason has a name.
+
+Common reflects this: it resets `margin` to `0` on almost every renderer it owns and lets parents own
+the rhythm. An application that reaches for margin first will produce two owners for one distance,
+which is `DOUBLE_OWNER`.
+
+## Scale
+
+`COMMON_SPACING_SCALE` is closed. The rule ID is the ordinal position on that scale. It is not the
+Tailwind step number, and the two diverge from MARGIN-5 onward.
+
+| Rule | Class | Value | Common token |
+| --- | --- | --- | --- |
+| MARGIN-0 | `m-0` | `0` | none |
+| MARGIN-1 | `m-1` | `.25rem` | none |
+| MARGIN-2 | `m-2` | `.5rem` | none |
+| MARGIN-3 | `m-3` | `.75rem` | none |
+| MARGIN-4 | `m-4` | `1rem` | none |
+| MARGIN-5 | `m-6` | `1.5rem` | none |
+| MARGIN-6 | `m-8` | `2rem` | none |
+
+Common publishes no margin token. `MARGIN-AUTO` is separate and carries no scale value.
+
+The rem values resolve to `0 / 4 / 8 / 12 / 16 / 24 / 32` CSS pixels only at a computed root of
+`16px`. Runtime checks use `expectedPx = remFactor * observedRootFontPx`.
+
+## Owner
+
+Each case names who owns the offset. The owner decides whether the application writes a class at all.
+
+| Owner | Meaning | Application writes |
+| --- | --- | --- |
+| `App` | The offset is a named application placement exception | The class |
+| A component name | Common already sets or resets the margin inside that component | Nothing. Compose it |
+| `—` | Common exposes no public path for this relationship | The class, recorded as a workaround |
+
+Writing a class where a component is the owner is `APP_REIMPLEMENTATION`. Adding a child margin next
+to a parent gap that already expresses the same distance is `DOUBLE_OWNER`.
+
+## Margin 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 |
+| --- | --- | --- |
+| `Label` | root | MARGIN-0 |
+| `MediaFrame` | root | MARGIN-0 |
+| `PageContainer` | root | MARGIN-AUTO |
+| `SectionHeader` | title | MARGIN-0 |
+| `SurfaceAccordionCard` | accordion trigger wrapper | MARGIN-0 |
+| `WorkspaceShell` | header, hasHeader | MARGIN-5 |
+
+## MARGIN-0 — `m-0` / `0`
+
+The offset is removed so a parent relationship becomes the single owner of the distance.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A native element brings a default margin that fights the composition | `App` | `<h2 className="m-0">` inside an app section that owns its gap |
+| Case 2 | Rendered article content whose rhythm is owned by the article | `MarkdownArticle` | Compose the article; no margin |
+| Case 3 | Any Common renderer that already resets its own margin | The component | Compose it; no margin |
+
+Not this rule: erasing a deliberate offset without moving that decision to a real owner leaves the
+relationship unowned.
+
+## MARGIN-1 — `m-1` / `.25rem`
+
+The smallest external clearance, for one precisely placed object that must sit just clear of an edge.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | An absolutely placed marker that would otherwise touch its containing edge | `App` | `<span className="absolute left-0 top-0 m-1">` |
+
+Not this rule: repeating it across siblings recreates a gap. Use GAP-1 on the parent.
+
+## MARGIN-2 — `m-2` / `.5rem`
+
+A compact offset for one independently placed object.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | An overlay caption or control anchored to a corner of an app-owned canvas | `App` | `<aside className="absolute bottom-0 right-0 m-2">` |
+
+Not this rule: a substitute for container padding or sibling gap. Use PADDING-2 or GAP-2.
+
+## MARGIN-3 — `m-3` / `.75rem`
+
+A dense but noticeable offset for one named placement exception.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A placed object where `.5rem` reads as cramped against a busy background | `App` | `<aside className="absolute right-0 top-0 m-3">` |
+
+Not this rule: repeated items in a list. Use GAP-3 on the parent.
+
+## MARGIN-4 — `m-4` / `1rem`
+
+The standard external offset for one object with an explicit placement exception.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A standalone object needing equal clearance from an enclosing boundary that cannot own it | `App` | `<aside className="m-4">` |
+| Case 2 | The trailing space after a code block inside article content | `FencedCodeBlock` | Compose the block; no margin |
+| Case 3 | The block rhythm around a horizontal rule in article content | `MarkdownArticle` | Compose the article; no margin |
+
+Not this rule: combining it with parent padding for the same edge-to-content purpose produces two
+owners for one distance.
+
+## MARGIN-5 — `m-6` / `1.5rem`
+
+A large offset that makes one standalone object visibly detached from its containing boundary.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | A named exception that must clear a boundary by more than the standard offset | `App` | `<aside className="m-6">` |
+| Case 2 | The separation below a workspace header | `WorkspaceShell` | Compose the shell; no margin |
+
+Not this rule: separation between substantial siblings. Use GAP-5 on the parent.
+
+## MARGIN-6 — `m-8` / `2rem`
+
+The largest external clearance, for a deliberately detached object.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | One object that must read as separated from everything around it, with a stated reason | `App` | `<aside className="m-8">` |
+
+Not this rule: general page rhythm, or repetition across siblings. Use GAP-6 on the parent.
+
+## MARGIN-AUTO — `mx-auto`
+
+Auto inline margins divide the free inline space and centre a width-constrained container. It carries
+no scale value and is not an offset decision.
+
+| Case | When | Owner | Render |
+| --- | --- | --- | --- |
+| Case 1 | An app-owned container that constrains its own width and must sit centred | `App` | `<main className="mx-auto max-w-3xl">` |
+| Case 2 | A page adopting the packaged measure and inset | `PageContainer` | Compose the container; it already centres |
+
+Not this rule: a full-width element, or an attempt to distribute space between siblings. Distribution
+belongs to the parent's layout.
+
+## Axis variants
+
+`mx-*` and `my-*` are not separate rules. They apply an existing rule to one axis when only one axis
+carries the exception.
+
+| Axis | Class | Meaning |
+| --- | --- | --- |
+| Inline | `mx-*` | The chosen rule applies to logical start and end only |
+| Block | `my-*` | The chosen rule applies to block start and end only |
+
+On the same element `m-*` and `mx-*` compete for the inline sides rather than adding. Adjacent block
+margins between siblings collapse, which is a second reason the parent gap is the reliable owner of
+sibling rhythm.
+
+## What this file does not decide
+
+Distance between siblings is [Gap](gap.md). The distance from a boundary to its content is
+[Padding](padding.md). Width constraints are [Measure](measure.md).