tracking(desktop): align shell chrome and settings with Astryx and DESIGN.md
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## 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
- #1303 (closed 2026-08-02) audited the 14 settings pages before Astryx was the renderer's design system; #1565 made Astryx the sole system the day before, and #1303's leftovers were folded into that migration (#1733, #1747, #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 #4571 and reduced to a row-only page with a two-tier control ladder in #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: #2188 (workbar panel interiors), #4582 (AppShell composition root R2, chihumyum), #2359 (icon scale), #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 #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)
- [ ] #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 #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 #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).
- [ ] #2359 — converge icon sizes onto a governed scale.
- [ ] #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 #4676, together with #3576 and #3527.
## Non-goals
- Rewriting tool-preview content cards or the ChatReasoning eject (review non-goals).
- New palettes or a new type scale.
- WorkHub behaviour (#3492) and IM onboarding hardening (#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.
Contributor guide
Assessment
This issue has not been assessed yet.