tracking(desktop): align shell chrome and settings with Astryx and DESIGN.md

[Astro-Han]

Goal

Bring the Desktop shell chrome and the settings pages onto the Astryx idiom and the DESIGN.md contract, so that every visible surface reads as one system: one surface ladder, one border means, one radius ladder, two ink tiers, and Astryx primitives at the seam.

This tracker owns the visual and structural work. Behavioural bugs and renderer performance are tracked separately in #4677; WorkHub lives in #3492.

Baseline and predecessors

• [Tracking] Settings pages polish pass — per-page visual and layout audit #1303 (closed 2026-08-02) audited the 14 settings pages before Astryx was the renderer's design system; refactor(ui): make Astryx the sole renderer design system #1565 made Astryx the sole system the day before, and [Tracking] Settings pages polish pass — per-page visual and layout audit #1303's leftovers were folded into that migration (refactor: adopt Astryx across settings and modules #1733, fix: align settings and modules with Astryx authority #1747, refactor(ui): finish the Astryx frontend migration #1853). The migration swapped controls; it did not rebuild the pages on Astryx's own settings template (Heading + Divider open groups, no stacked cards, no nested containers). docs/settings-astryx-deep-review.zh-CN.md (C1–C10) records the gap; About was rebuilt on the template in refactor(desktop): rebuild the About page as labeled settings groups #4571 and reduced to a row-only page with a two-tier control ladder in fix(desktop): reduce the About page to rows of one shape #4857; the merged About page is the reference; 13 pages remain.
• docs/frontend-architecture-astryx-review-2026-08-09.md: raw-control blockers 0; remaining risk is AppShell concentration (A1–A3), CSS dialect sprawl (A7), and product chrome over Astryx controls (P3.1).
• Already tracked elsewhere and linked here rather than duplicated: tracking(workbar): replace the hand-written tab strip with TabList, and close the panel gaps that are left #2188 (workbar panel interiors), refactor(desktop): make AppShell a composition root, R2 (migrate by call site) #4582 (AppShell composition root R2, chihumyum), Converge icon sizes onto a governed scale #2359 (icon scale), test(desktop): enumerate failure and edge states for high-traffic surfaces #3944 (failure and edge states of high-traffic surfaces).

Work items

Each item is one PR with BEFORE/AFTER Storybook captures (light and dark, same stories, same viewport) in the PR body.

Titlebar

• Land or supersede fix(desktop): plan titlebar chrome from the front surface #2628 (jackwener, plan titlebar chrome from the front surface; conflicts with main since 08-27) before touching titlebar geometry.
• Titlebar geometry and identity: one height on the 4px rhythm, session identity from titlebar-session-identity.tsx as the only title authority, chrome actions as Astryx Button/Toolbar, no product shadow.
• Titlebar dim and modal sync (titlebar-dim-color.ts, titlebar-modal-sync.ts) read colour from the painted root per DESIGN.md §8, never from a token string.

Workbar (right side)

• tracking(workbar): replace the hand-written tab strip with TabList, and close the panel gaps that are left #2188 — rewritten as the Workbar tracker (see R1 below): shell chrome plus one sub-issue per panel interior. Owned here; sub-issues open for claiming.

Session rail (left sidebar)

• Rows on the Astryx List/Item idiom: 32–36px rows, dividers instead of cards, status via StatusDot (no decorative Badge).
• Hover card, rename dialog and context menu on Astryx Tooltip/Dialog/DropdownMenu with the Floating Recipe (DESIGN.md §5).
• Project grouping header and pin affordance per Discussion What should Pin do in the “By project” view? #4453 outcome.

Settings (13 pages, in groups of 2–3 per PR, following About as merged in #4857)

• General, Appearance, Data
• Memory, Projects, Subagents
• Providers overview and connection detail (keep the multi-level IA; fix C1–C4 inside it)
• Bots overview, detail, onboarding modal
• Usage, Web search, Health, Permission, Daily review
• Rules for every page: open groups with Heading + Divider (no stacked cards, C1), no nested containers (C2), no decorative Badge (C3), one primary action per view (C4), no accent as texture (C5), unified row grammar (C7), no dashboard stat tiles (C8).
• Row-end controls follow the Astryx component docs, not the settings templates: actions are Button (secondary when the action changes state, ghost otherwise; primary only for the single task-completing action of the view, if any), navigation is Link. A row-end Link takes the same inline padding as the sm buttons so text edges align down the column (see fix(desktop): reduce the About page to rows of one shape #4857).

Cross-cutting

• CSS dialect: move remaining surface rules out of maka-tokens.css and reference-shell.css into styles/** per docs/frontend-css-governance.md; freeze new agents-* class names (P3.3).
• Shrink quote-chip, turn-footer and lineage Button overrides to themeProps (P3.1).
• Converge icon sizes onto a governed scale #2359 — converge icon sizes onto a governed scale.
• refactor(desktop): make AppShell a composition root, R2 (migrate by call site) #4582 — AppShell composition root R2 (chihumyum owns; the titlebar and detail-panel items above land as slices under its definition of done rather than as edits to app-shell.tsx).
• Frontend agent rules (apps/desktop/AGENTS.md, packages/ui/AGENTS.md) and the xds + Storybook MCP entries — pending Discussion [DISCUSS] What should the repository tell coding agents, and where? #4676, together with docs: add AGENTS.md #3576 and Adopt Storybook's official MCP addon to give agents a queryable component interface #3527.

Non-goals

• Rewriting tool-preview content cards or the ChatReasoning eject (review non-goals).
• New palettes or a new type scale.
• WorkHub behaviour (tracking(desktop): evolve WorkHub into a per-Runtime-Host conversational coordinator #3492) and IM onboarding hardening (tracking(bots): harden onboarding after V1 #4327).

Verification

• Storybook stories for every touched surface; apps/desktop/e2e where behaviour exists.
• Inventory regen stays at blocker 0; DESIGN.md contract tests pass.

[Astro-Han]

take