From 23dde4de5c1efa44b9d479b9639b26b7a1417059 Mon Sep 17 00:00:00 2001
From: Yang Wu <1425326620@qq.com>
Date: Sat, 5 Sep 2026 03:23:05 +0800
Subject: [PATCH 1/2] docs: audit desktop and frontend references

Refs #3522.

Generated-by: OpenAI Codex
---
 docs/astryx-alignment-inventory.md            | 20 +++++--
 docs/astryx-full-surface-audit.md             | 22 +++++--
 ...d-architecture-astryx-review-2026-08-09.md | 44 ++++++++++----
 docs/frontend-css-governance.md               | 48 +++++++++++-----
 docs/frontend-css-governance.zh-CN.md         | 57 +++++++++++--------
 docs/settings-astryx-deep-review.zh-CN.md     | 17 +++++-
 6 files changed, 145 insertions(+), 63 deletions(-)

diff --git a/docs/astryx-alignment-inventory.md b/docs/astryx-alignment-inventory.md
index 264191655b..8d305d90ad 100644
--- a/docs/astryx-alignment-inventory.md
+++ b/docs/astryx-alignment-inventory.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.astryx-alignment-inventory
+title: "Astryx alignment inventory"
+language: en
+source_language: en
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -17,12 +27,12 @@
   under the License.
 -->
 
-> **Superseded for file-level coverage:** see [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md) (one row per product surface file). This document remains the family-level wiki map and fix log from the first alignment pass.
+> **Historical family-level fix log.** File-level coverage and current severities are generated in [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md). This document records the first alignment pass; its status cells and remaining-polish list are not a current backlog. On 2026-09-05, the generated check reported 249 files, 0 blockers, 0 reimplementations, 1 polish item, and 248 aligned files.
 
 # Astryx alignment inventory
 
-Maps [Astryx wiki](https://github.com/facebook/astryx/wiki) conventions onto
-Maka product surfaces. Severity: **blocker** (raw control when an Astryx twin
+This pass mapped [Astryx wiki](https://github.com/facebook/astryx/wiki) conventions onto
+Maka product surfaces. At the time, severity meant **blocker** (raw control when an Astryx twin
 exists / broken hierarchy) · **reimplementation** (a public `@maka/ui` export
 shadows a shipped Astryx component — a review signal, not proof) · **polish**
 (off-scale px, density).
@@ -93,7 +103,9 @@ shadows a shipped Astryx component — a review signal, not proof) · **polish**
 - Plan execution expand → Astryx `Collapsible`.
 - Workbar tool picker → Astryx `List` + `ListItem`; visible descriptions and native row interaction.
 
-## Remaining polish (non-blocker)
+## Remaining polish recorded by the first pass (historical)
 - Quote chips / prompt-rail ticks stay product-shaped hit targets.
 - Workbar tab strip stays custom for dnd-kit + `role=tab`.
 - Nested button prohibition on SideNavItem endContent (documented intentional).
+
+Run `npm run astryx:surface-inventory` for the current file universe and severity result.
diff --git a/docs/astryx-full-surface-audit.md b/docs/astryx-full-surface-audit.md
index 9ea0fe70ed..a4f6540125 100644
--- a/docs/astryx-full-surface-audit.md
+++ b/docs/astryx-full-surface-audit.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.astryx-full-surface-audit-2026-08-09
+title: "Astryx full surface audit"
+language: en
+source_language: en
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -25,7 +35,9 @@ Scope: every product surface under `apps/desktop/src/renderer/**` and `packages/
 
 This pass **read and analyzed** settings pages/modules, shell/chat/workbar/panels, module hubs, packages/ui compositions, and product CSS — not only inventory scripts.
 
-## Verdict
+> **Historical audit record.** The 183-file totals, status table, fix list, and backlog below belong to the named branch and date. They are not current coverage or an open-work queue. On 2026-09-05, `npm run astryx:surface-inventory` verified the generated [file-level inventory](./astryx-surface-file-inventory.md) at 249 files, 0 blockers, 0 reimplementations, 1 polish item, and 248 aligned files. The remaining polish row is `packages/ui/src/composer-message-queue.tsx`.
+
+## Verdict at the audited commit
 
 | Layer | State |
 |-------|--------|
@@ -76,10 +88,10 @@ Aligned: skills-panel, scheduled-task-*, daily-review-panel, module-pages, compo
 4. **Tool / agent / web-search preview cards** — product transcript content chrome, not generic controls.
 5. **DeepResearchProgressPanel** — product progress composition; kit-ify is a dedicated design task.
 6. **Quote chip / turn footer CSS** — still product-geometry overrides on Astryx controls; shrink chrome gradually.
-7. **Logo 44 / swatch 34 / session-context 40** — decorative or band heights, not control rhythm 28/32/36.
+7. **Logo 44 / swatch 34 / session-context 40** — this pass treated them as decorative or band heights. The follow-up review recorded them as the four concrete inventory polish rows and normalized them to 36/36/32; they are not a current exception.
 8. **ChatReasoning / markdown density contracts** — documented product overrides.
 
-## Remaining backlog (priority)
+## Remaining backlog at the audited commit (historical)
 
 ### P1 — visual system
 
@@ -99,9 +111,9 @@ Aligned: skills-panel, scheduled-task-*, daily-review-panel, module-pages, compo
 
 - shrink `.maka-quote-chip-remove` / `.maka-turn-footer-action` / lineage badge overrides.
 - retire dead tool-terminal CSS if unused.
-- inventory polish false-positives for logo/swatch heights.
+- ~~inventory polish false-positives for logo/swatch heights.~~ Resolved by the follow-up review as real polish rows and normalized to the shared rhythm.
 
-## Method
+## Original method
 
 1. Regenerated path inventory (183 files).
 2. Pattern scan: raw controls, role=button, hand empties, role=alert.
diff --git a/docs/frontend-architecture-astryx-review-2026-08-09.md b/docs/frontend-architecture-astryx-review-2026-08-09.md
index 093b60ec33..f0c571a755 100644
--- a/docs/frontend-architecture-astryx-review-2026-08-09.md
+++ b/docs/frontend-architecture-astryx-review-2026-08-09.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.architecture-astryx-review-2026-08-09
+title: "Frontend architecture and Astryx coverage review"
+language: en
+source_language: en
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -23,11 +33,24 @@
 **HEAD:** `0ad579d33` (`feat(ui): align high-traffic chrome with Astryx primitives (#2580)` on `main`)  
 **Scope:** `apps/desktop/src/renderer/**`, `packages/ui/src/**`  
 **Method:** file-level inventory regen + pattern scan + deep reads of shell/settings/modules/ui; prior art `docs/astryx-full-surface-audit.md`, `DESIGN.md`, `docs/astryx-surface-file-inventory.md`  
-**Evidence log:** goal scratch `frontend-review-scan.log` (inventory totals, greps, spot-checks, inventory unit tests)
+**Original evidence:** the committed audit at `0ad579d33` and follow-up implementation at `d68e9d775`; the scratch scan log named by the original review was not committed.
 
 ---
 
-## Executive verdict
+> **Historical review record.** The findings, file sizes, inventory counts, and backlog below describe the audited commit and the follow-up branch, not current `main`. Current file-level coverage is generated in [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md); current renderer ownership is recorded in `apps/desktop/renderer-architecture.json` and the feature README files.
+
+## Current status checked on 2026-09-05
+
+- The generated inventory now covers **249 files: 0 blockers, 0 reimplementations, 1 polish item, and 248 aligned files**. The remaining polish row is the raw draft editor in `packages/ui/src/composer-message-queue.tsx`.
+- `WorkbarController` is now a real boundary at `apps/desktop/src/renderer/features/workbar/controller/use-workbar-controller.ts`, and `WorkbarHost` owns the rendered surface. The A3 direction below therefore landed; its old `session-workbar*` anchors no longer exist.
+- Module Hub, Goals, Task Entry, Session Navigation, Session Collaboration, and Workbar have feature boundaries below `AppShell`. `apps/desktop/renderer-architecture.json` still classifies `app-shell.tsx` as the `app-shell-integration-knot`; at 3,293 lines, the broader A1 concentration remains current.
+- Settings still accepts section requests through `use-settings-modal.ts`, persisted section state, and the `maka:jumpToSettingsSection` event in `settings-surface.tsx`. The A4 convergence remains planned.
+- `packages/ui/src/composer.tsx` is now 2,284 lines, so the A5 concentration remains current. The tool-output implementation named in A6 now lives in `packages/ui/src/tool-activity/tool-result-preview.tsx`.
+- Astryx patches are versioned with the installed dependency. `patches/README.md` is the stable authority; do not use the `0.3.0` filename from the historical table as a current path.
+
+Reproduce the current file-level result with `npm run astryx:surface-inventory`.
+
+## Executive verdict at the audited commit
 
 The product already has a **correct intended layering**:
 
@@ -45,7 +68,7 @@ Remaining risk is not “missing Buttons.” It is:
 
 ---
 
-## 1. Layering map (as shipped)
+## 1. Layering map at the audited commit
 
 ```
 Electron frame
@@ -84,7 +107,7 @@ Electron frame
 
 ---
 
-## 2. Architecture review (simplification / elevation)
+## 2. Architecture review at the audited commit
 
 Severity: **blocker** = structural cost that blocks every feature; **high** = clear multi-surface tax; **polish** = cleanups that can wait.
 
@@ -166,7 +189,7 @@ Severity: **blocker** = structural cost that blocks every feature; **high** = cl
 
 ---
 
-## 3. Astryx style / component coverage gaps
+## 3. Astryx style / component coverage gaps at the audited commit
 
 ### 3.1 Inventory baseline
 
@@ -208,7 +231,6 @@ These were **not** invent-from-whole-cloth “logo false positives” in the abs
 | **medium (P2)** | Keyboard help raw `<h3>` | `keyboard-help.tsx` | **Fixed** → `Heading level={3}` |
 | **medium (P2)** | Web tool result raw `<a>` | `tool-result-preview.tsx` | **Fixed** → Astryx `Link` |
 | **medium (P1/P2)** | Deep Research plate washes | `deep-research.css` | **Fixed** → wash tokens |
-| **medium (P2)** | Keyboard help raw `<h3>` | `keyboard-help.tsx` | `Heading` / `Text` |
 | **low (P3)** | Quote chip / remove / turn footer / lineage re-chrome Astryx Button | `packages/ui/src/styles.css`, `quote-ref-chip.tsx`, `chat-turn.tsx` | shrink overrides; prefer Badge/Token for lineage |
 | **low (P3)** | Workbar tab busy uses `Loader2` | `session-workbar.tsx` | `Spinner` if it means loading |
 
@@ -230,7 +252,7 @@ These were **not** invent-from-whole-cloth “logo false positives” in the abs
 | **intentional** | Tool/agent/web preview card chrome | `primitives/chat.tsx`, `styles.css` tool families | content DS, not form controls |
 | **intentional** | Chat empty heroes | `chat-empty-hero.tsx` | welcome surface ≠ EmptyState |
 | **intentional** | ChatReasoning lab eject | `astryx-chat-reasoning.tsx` | keep until stable peer |
-| **intentional** | Astryx patches | `patches/@astryxdesign+core+0.3.0.patch`, `patches/README.md` | conversationKey / tool row / List aria / UA-CH |
+| **intentional** | Astryx patches | `patches/README.md` and the dependency-versioned Astryx patch named there | conversationKey / tool row / List aria / UA-CH at the audited commit |
 
 ### 3.3 Loading kit sprawl (architecture × Astryx)
 
@@ -249,7 +271,7 @@ Empty/error largely share Astryx. **Loading** still has 6+ dialects:
 
 ---
 
-## 4. Prioritized backlog (actionable)
+## 4. Original prioritized backlog (historical)
 
 ### P0 — Architecture (no visual swap required)
 
@@ -298,7 +320,7 @@ Empty/error largely share Astryx. **Loading** still has 6+ dialects:
 
 ---
 
-## 5. Spot-check log (verification)
+## 5. Original spot-check log
 
 Claims re-checked on disk at review time:
 
@@ -317,7 +339,7 @@ Claims re-checked on disk at review time:
 
 ---
 
-## 6. Summary for decision-makers
+## 6. Summary recorded at the audited commit
 
 | Question | Answer |
 |----------|--------|
@@ -326,6 +348,6 @@ Claims re-checked on disk at review time:
 | Biggest remaining architectural win? | **De-god AppShell** (P0) — multi-week; not done in this pass. |
 | What to leave alone? | ChatReasoning eject, tool preview content cards, providers multi-level IA, residual quote/turn Button geometry until a dedicated chrome pass. |
 
-## 7. Implementation note (follow-up branch)
+## 7. Historical implementation note
 
 P1 elevation/wash, off-rhythm heights, and P2 Toolbar/Kbd/Heading/Link were implemented on branch `fix/astryx-review-debt-2026-08-09` after the analysis-only review. Architecture P0 (AppShell controllers) remains backlog.
diff --git a/docs/frontend-css-governance.md b/docs/frontend-css-governance.md
index a89513f204..05e01dad76 100644
--- a/docs/frontend-css-governance.md
+++ b/docs/frontend-css-governance.md
@@ -1,3 +1,14 @@
+---
+doc_id: frontend.css-governance
+title: "Frontend CSS governance"
+language: en
+source_language: en
+counterpart: ./frontend-css-governance.zh-CN.md
+implementation_status: current
+document_status: stable
+translation_status: synced
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -21,53 +32,59 @@
 
 [中文](./frontend-css-governance.zh-CN.md)
 
-Maka's frontend styling combines Astryx, `@maka/ui` product compositions, and renderer surface CSS. Cascade order is an explicit contract rather than an implementation detail.
+Maka's frontend styling combines Astryx, `@maka/ui` product compositions, and renderer surface CSS. Cascade order is an explicit contract rather than an implementation detail. This document describes the current contract for contributors working in `apps/desktop/src/renderer/**` and `packages/ui/src/**`.
 
 ## 1. Entry file
 
 - `apps/desktop/src/renderer/styles.css` is an entry file only.
 - It may contain `@import` and other top-level orchestration statements.
 - New per-surface selector blocks belong in `apps/desktop/src/renderer/styles/**/*.css`.
-- Historical recipes at the end of `maka-tokens.css` and `reference-shell.css` are transitional exceptions. Do not add new surface rules to them.
+- `cascade-layers.css`, `maka-tokens.css`, and `reference-shell.css` are deliberate root-level exceptions. The first declares cascade order, the second owns shared renderer tokens and legacy recipes, and the third carries transitional shell compatibility. Do not add ordinary surface rules to them.
 
 ### Selector naming
 
-- Shared renderer and `@maka/ui` selectors use the kebab-case `.maka-*` dialect.
+- New selectors shared across renderer surfaces or exported by `@maka/ui` use the kebab-case `.maka-*` dialect.
 - The established `styles/settings/**` surface uses camelCase `.settings*` selectors. Keep that dialect for settings-local selectors instead of mixing both forms within one surface.
+- Feature-local namespaces already exist, including `.workhub-*`. Keep them local to their feature; do not turn them into a second cross-surface dialect. Legacy `.agents-*` and `.detailPane` names are compatibility debt, not examples for new selectors.
 - Moving existing settings selectors between concern files does not require a repository-wide rename; any future naming migration should be handled as an explicit compatibility change.
 
 ## 2. Layers
 
-- Pure presentation rules should use `@layer base` or `@layer components` where practical.
+- `apps/desktop/src/renderer/cascade-layers.css` is the single owner of the order: `reset`, `theme`, `base`, `astryx-components`, `astryx-tokens`, then `components`.
+- `styles.css` imports Astryx's neutral component sheet into `astryx-components`, the generated Maka theme into `astryx-tokens`, and `@maka/ui` plus renderer surfaces into `components`. `maka-tokens.css` declares its own `base` and `components` blocks.
+- Keep ordinary product presentation in `components`. Use another existing layer only when that layer owns the rule's semantics.
 - Use `@import "./file.css" layer(components)` only when the build chain explicitly supports it.
 - Do not place `@import` inside an `@layer` block.
 
-Astryx reset and component layers come first; Maka base tokens and product `components` come later. Keep layer ownership at the closest existing seam instead of adding a higher-priority compatibility layer.
+Keep layer ownership at the closest existing seam instead of adding a higher-priority compatibility layer. Do not reorder the declared layers from a surface stylesheet; a cascade-order change belongs in `cascade-layers.css` and needs rendered regression evidence.
 
-## 4. `!important`
+## 3. `!important`
 
-- `!important` is allowed by default only for accessibility helpers such as `.maka-visually-hidden`, and for reduced-motion or e2e-fixture overrides.
-- Every other use requires an adjacent `Justified:` comment.
+- Default exceptions are accessibility helpers such as `.maka-visually-hidden`, reduced-motion and e2e-fixture overrides, and the centralized native-cursor policy.
+- Narrow compatibility and product overrides remain in `reference-shell.css`, `styles/settings/usage.css`, and `packages/ui/src/styles.css`. They are explicit debt or bounded component fixes, not precedent for another override.
+- Every new use outside the default exceptions needs an adjacent comment that names the competing rule, explains why the normal component or layer seam cannot express the fix, and states when the override can be removed. `Justified:` is the conventional marker.
 - Prefer fixing the primitive API or semantic class when it can express the behavior directly.
 
-## 5. Tokens
+## 4. Tokens
 
-- Shared custom properties belong in `apps/desktop/src/renderer/maka-tokens.css`.
-- Component-local properties are allowed only with a `/* local: ... */` comment.
-- Do not add raw colors, radii, or ungoverned z-index values.
+- Shared renderer custom properties belong in `apps/desktop/src/renderer/maka-tokens.css`.
+- `apps/desktop/src/renderer/astryx-theme/maka.css` is generated by `npm run astryx:theme`; do not edit it by hand.
+- Component-local properties are allowed only near their owner with a `/* local: ... */` comment.
+- Do not add raw colors for semantic roles, one-off radii that duplicate the radius ladder, or ungoverned z-index values. Literal geometry is acceptable only when it describes a local measured constraint rather than a reusable design role.
 
-## 6. How these rules are checked
+## 5. How these rules are checked
 
 These rules are conventions enforced in review. Static correctness belongs to
 Biome, Knip, and typecheck; accessibility keeps its focused check. CSS usage and
 Story prose are not decided by repository-wide regex baselines.
 
+- `npm run astryx:surface-inventory` verifies that the generated surface inventory matches disk and fails on new raw interactive-control blockers. It does not prove the entire CSS governance contract.
 - Renderer CSS behavior is verified where it renders: Storybook, the app, or an
   e2e assertion on the real surface.
 - Remove selectors with the source or surface that owned them instead of
   maintaining an allowlist of strings that may be generated at runtime.
 
-## 7. Change order
+## 6. Change order
 
 When changing renderer CSS:
 
@@ -76,8 +93,9 @@ When changing renderer CSS:
 3. Remove dead selectors.
 4. Remove remaining `!important` only after primitive and layer ownership is stable.
 
-## 8. Governing principles
+## 7. Governing principles
 
+- Keep the CI guardrails credible before using their green result as evidence for structural work.
 - Delete dead CSS before aesthetic refactoring.
 - Resolve shared `Button`, `Textarea`, and `EmptyState` overrides at the component API seam instead of accumulating renderer specificity.
 - Every change to cascade order requires the narrowest relevant regression check on the rendered surface.
diff --git a/docs/frontend-css-governance.zh-CN.md b/docs/frontend-css-governance.zh-CN.md
index cbf34b11bb..014e97aecf 100644
--- a/docs/frontend-css-governance.zh-CN.md
+++ b/docs/frontend-css-governance.zh-CN.md
@@ -1,3 +1,14 @@
+---
+doc_id: frontend.css-governance
+title: "前端 CSS 治理规范"
+language: zh-CN
+source_language: en
+counterpart: ./frontend-css-governance.md
+implementation_status: current
+document_status: stable
+translation_status: synced
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -21,60 +32,56 @@
 
 [English](./frontend-css-governance.md)
 
-本仓库的前端样式体系由 Astryx、`@maka/ui` 产品组合样式和 renderer surface CSS 组成。级联顺序必须被明确约束，不能随意改动。
+本仓库的前端样式体系由 Astryx、`@maka/ui` 产品组合样式和 renderer surface CSS 组成。级联顺序是明确的实现契约，不能随意改动。本文描述贡献者修改 `apps/desktop/src/renderer/**` 与 `packages/ui/src/**` 时应遵守的当前契约。
 
 ## 1. 入口文件规则
 
 - `apps/desktop/src/renderer/styles.css` 只能作为样式入口文件使用。
 - 它只允许包含 `@import` 和顶层入口编排语句。
 - 新增的 per-surface selector 规则块必须放在 `apps/desktop/src/renderer/styles/**/*.css`。
-- `maka-tokens.css` 尾部的历史 recipe 和 `reference-shell.css` 是待收敛的 transitional exceptions；不要继续向这两个例外增加 surface 规则。
+- `cascade-layers.css`、`maka-tokens.css` 和 `reference-shell.css` 是有意保留在根目录的例外：它们分别负责级联顺序、renderer 共享 token 与历史 recipe，以及待收敛的 shell 兼容规则。普通 surface 规则不要写进这些文件。
 
 ### Selector 命名
 
-- renderer 与 `@maka/ui` 的共享 selector 使用 kebab-case `.maka-*` 方言。
+- 新增的跨 renderer surface 共享 selector，以及 `@maka/ui` 对外 selector，使用 kebab-case `.maka-*` 方言。
 - 已有的 `styles/settings/**` surface 使用 camelCase `.settings*` selector；settings 内的新 selector 应延续该方言，避免同一 surface 混用两套命名。
+- 现有 feature 可以保留自己的局部命名空间，例如 `.workhub-*`，但不得把它扩散成第二套跨 surface 方言。遗留的 `.agents-*` 与 `.detailPane` 属于兼容债务，不能作为新增 selector 的范例。
 - 在 settings 的 concern 文件之间移动现有 selector 时不要求全仓重命名；未来若统一命名，应作为显式兼容性改动单独推进。
 
 ## 2. Layer 规则
 
-- 纯展示规则应尽量放进：
-  - `@layer base`
-  - `@layer components`
+- `apps/desktop/src/renderer/cascade-layers.css` 是级联顺序的唯一权威：`reset`、`theme`、`base`、`astryx-components`、`astryx-tokens`、`components`。
+- `styles.css` 把 Astryx 中性组件样式放入 `astryx-components`，把生成的 Maka 主题放入 `astryx-tokens`，并把 `@maka/ui` 与 renderer surface 放入 `components`。`maka-tokens.css` 自己声明 `base` 与 `components` 块。
+- 普通产品展示规则应放在 `components`；只有现有 layer 确实拥有该规则的语义时，才使用其他 layer。
 - 只有在构建链明确支持时，才使用 `@import "./file.css" layer(components)`。
 - 不要使用 `@layer { @import ... }` 这种写法。
 
-Astryx reset 和组件层在前，Maka base token 与产品 `components` 在后。应在最近的现有职责缝隙解决覆盖，不再增加更高优先级的兼容层。
+应在最近的现有职责缝隙解决覆盖，不再增加更高优先级的兼容层。surface 样式文件不得重新排序全局 layer；需要改变级联顺序时，应修改 `cascade-layers.css`，并提供真实渲染回归证据。
 
-## 4. `!important` 使用规则
+## 3. `!important` 使用规则
 
-- 默认只允许两类场景使用 `!important`：
-  - 无障碍辅助规则，例如 `.maka-visually-hidden`
-  - reduced-motion / e2e-fixture 这类测试或可访问性覆盖
-- 其他任何 `!important` 都必须同时满足：
-  - 就地写明 `Justified:` 注释
+- 默认例外包括无障碍辅助规则（例如 `.maka-visually-hidden`）、reduced-motion / e2e-fixture 覆盖，以及集中管理的原生 cursor 策略。
+- `reference-shell.css`、`styles/settings/usage.css` 与 `packages/ui/src/styles.css` 中仍有少量兼容或产品覆盖。它们是显式债务或有边界的组件修复，不能作为继续增加覆盖的先例。
+- 新增的非默认用法必须紧邻说明注释：指出与哪条规则冲突、为什么常规组件或 layer 职责无法表达，以及何时可以删除。约定使用 `Justified:` 作为标记。
 - 如果 primitive API 或语义类可以直接表达，优先在该职责层解决，不要继续叠更多 `!important`。
 
-## 5. Token 规则
+## 4. Token 规则
 
-- 自定义 CSS 变量统一放在：
-  - `apps/desktop/src/renderer/maka-tokens.css`
-- 只有组件局部变量允许例外，但必须带：
-  - `/* local: ... */`
-- 禁止新增以下硬编码值：
-  - 颜色
-  - radius
-  - 未纳入约束体系的 z-index
+- renderer 共享自定义属性统一放在 `apps/desktop/src/renderer/maka-tokens.css`。
+- `apps/desktop/src/renderer/astryx-theme/maka.css` 由 `npm run astryx:theme` 生成，不得手工修改。
+- 组件局部属性只能放在其 owner 附近，并带 `/* local: ... */` 注释。
+- 不要为语义角色新增原始颜色，不要用一次性 radius 重复现有圆角阶梯，也不要新增无治理的 z-index。只有在描述组件内部的实测约束、而非可复用设计角色时，才可使用字面几何值。
 
-## 6. 这些规则靠什么保证
+## 5. 这些规则靠什么保证
 
 这些规则靠评审保证。静态正确性交给 Biome、Knip 和 typecheck；accessibility
 保留聚焦的检查。CSS 使用关系和 Story 文案不再由全仓 regex baseline 决定。
 
+- `npm run astryx:surface-inventory` 会验证生成的 surface inventory 与磁盘一致，并阻止新增 raw interactive-control blocker；它不等于完整的 CSS 治理证明。
 - renderer CSS 的行为在它真正渲染的地方验证：Storybook、app，或对真实界面的 e2e 断言。
 - selector 应随其 source 或 surface 一起删除，不维护运行时字符串 allowlist。
 
-## 7. 推荐改动顺序
+## 6. 推荐改动顺序
 
 调整 renderer CSS 时，建议按下面顺序推进：
 
@@ -83,7 +90,7 @@ Astryx reset 和组件层在前，Maka base token 与产品 `components` 在后
 3. 清理 dead selector。
 4. 只有在 primitive / layer 架构已经稳定后，再移除剩余 `!important`。
 
-## 8. 当前治理原则
+## 7. 当前治理原则
 
 - 先保证 CI 护栏可信，再做结构收敛。
 - 先删 dead CSS，再谈样式“美化性重构”。
diff --git a/docs/settings-astryx-deep-review.zh-CN.md b/docs/settings-astryx-deep-review.zh-CN.md
index 63e152b75d..7b7fb6a997 100644
--- a/docs/settings-astryx-deep-review.zh-CN.md
+++ b/docs/settings-astryx-deep-review.zh-CN.md
@@ -1,3 +1,13 @@
+---
+doc_id: frontend.settings-astryx-review-2026-08-03
+title: "Maka 设置页 Astryx 深度审计"
+language: zh-CN
+source_language: zh-CN
+implementation_status: historical
+document_status: historical
+translation_status: source-only
+last_verified: 2026-09-05
+---
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
@@ -17,10 +27,11 @@
   under the License.
 -->
 
-# Maka 设置页深度 Review——以 Astryx 设计语言为基准
+# Maka 设置页 Astryx 深度审计（历史记录）
 
-> 2026-08-03,基于 `settings/astryx-refactor` 分支(已 rebase 到最新 main)。
-> 审计方式:Storybook 全页截图(中/英 × 亮/暗)+ Astryx 官方 `settings` / `settings-dialog` 模板与 `astryx docs` 原文精读。
+> **生命周期：历史。** 下文记录的是 2026-08-03、`#1972` 落地前的设置页问题与重构目标，不是当前缺陷清单。该方案已经由 `refactor(desktop): rebuild Settings on the Astryx open-group idiom (#1972)` 落地。当前实现以 `settings/settings-section.tsx`、`settings/settings-rows.tsx` 和 `styles/settings/rows.css` 为准；全量 surface 覆盖以生成的 [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md) 为准。
+>
+> 原审计基于 `settings/astryx-refactor` 分支，使用 Storybook 全页截图（中/英 × 亮/暗）、Astryx 官方 `settings` / `settings-dialog` 模板和 `astryx docs` 原文。2026-09-05 复核确认：`SettingsSection` 的开放行组、`SettingsRow` / `SettingsField` / `SettingsActions` 三种行语法，以及以 `StatusDot` + 文本为主的状态表达均已进入当前实现；页面数量、按钮数量和 CSS 行数等下文数字只描述当时快照。
 
 ## 一、Astryx 官方设置语言到底是什么
 

From 9b176466c826db760cb67c05c6580f49d2e7a7ee Mon Sep 17 00:00:00 2001
From: Yang Wu <1425326620@qq.com>
Date: Sun, 6 Sep 2026 01:51:42 +0800
Subject: [PATCH 2/2] docs: document missing !important overrides

---
 docs/frontend-css-governance.md       | 2 +-
 docs/frontend-css-governance.zh-CN.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/frontend-css-governance.md b/docs/frontend-css-governance.md
index 05e01dad76..eb9d529a3e 100644
--- a/docs/frontend-css-governance.md
+++ b/docs/frontend-css-governance.md
@@ -61,7 +61,7 @@ Keep layer ownership at the closest existing seam instead of adding a higher-pri
 ## 3. `!important`
 
 - Default exceptions are accessibility helpers such as `.maka-visually-hidden`, reduced-motion and e2e-fixture overrides, and the centralized native-cursor policy.
-- Narrow compatibility and product overrides remain in `reference-shell.css`, `styles/settings/usage.css`, and `packages/ui/src/styles.css`. They are explicit debt or bounded component fixes, not precedent for another override.
+- Narrow compatibility and product overrides remain in `reference-shell.css`, `styles/settings/usage.css`, `styles/shell-layout.css`, `styles/sidebar.css`, and `packages/ui/src/styles.css`. The shell layout override keeps SideNav width following its animated wrapper; sidebar overrides reconcile SideNav spacing and borders with unlayered StyleX rules. They are explicit debt or bounded component fixes, not precedent for another override.
 - Every new use outside the default exceptions needs an adjacent comment that names the competing rule, explains why the normal component or layer seam cannot express the fix, and states when the override can be removed. `Justified:` is the conventional marker.
 - Prefer fixing the primitive API or semantic class when it can express the behavior directly.
 
diff --git a/docs/frontend-css-governance.zh-CN.md b/docs/frontend-css-governance.zh-CN.md
index 014e97aecf..40d6a08c9c 100644
--- a/docs/frontend-css-governance.zh-CN.md
+++ b/docs/frontend-css-governance.zh-CN.md
@@ -61,7 +61,7 @@ last_verified: 2026-09-05
 ## 3. `!important` 使用规则
 
 - 默认例外包括无障碍辅助规则（例如 `.maka-visually-hidden`）、reduced-motion / e2e-fixture 覆盖，以及集中管理的原生 cursor 策略。
-- `reference-shell.css`、`styles/settings/usage.css` 与 `packages/ui/src/styles.css` 中仍有少量兼容或产品覆盖。它们是显式债务或有边界的组件修复，不能作为继续增加覆盖的先例。
+- `reference-shell.css`、`styles/settings/usage.css`、`styles/shell-layout.css`、`styles/sidebar.css` 与 `packages/ui/src/styles.css` 中仍有少量兼容或产品覆盖。shell layout 覆盖让 SideNav 宽度跟随执行动画的外层容器；sidebar 覆盖用于协调 SideNav 的间距、边框与未分层的 StyleX 规则。它们是显式债务或有边界的组件修复，不能作为继续增加覆盖的先例。
 - 新增的非默认用法必须紧邻说明注释：指出与哪条规则冲突、为什么常规组件或 layer 职责无法表达，以及何时可以删除。约定使用 `Justified:` 作为标记。
 - 如果 primitive API 或语义类可以直接表达，优先在该职责层解决，不要继续叠更多 `!important`。