Studio design review and parity tracking

[peppescg]

Parent: #1774. Review tracker for the design-alignment sub-issues under #1736.

Status: active. The design baseline for this batch is frozen as of 2026-09-24;
later design changes are explicit amendments to the affected work item.

Role

• Track the component/token gap inventory and the visual and interaction result across
  the shell, auth/recovery, settings, chat, schedules, skills, memory, and learning.
• Maintainers review before/after desktop and mobile screenshots, the key interaction
  flow, keyboard behavior, focus, and light/dark contrast for each surface. No separate
  design-author sign-off is required. Ordinary code review owns BFF, contract, and
  security correctness.
• Record intentional deviations once, here or in the owning issue, so a review can tell
  a product decision from an unfinished port. The local shared-control system remains
  the foundation; this batch does not add an external UI-kit dependency.
• Keep the accessibility and responsive sweep integrated with each surface, then verify
  consistency across the finished app.

Decisions for this batch

• Port the selected code and user-visible behavior closely while preserving ADR 0351:
  browser through the BFF, the published SDK, one origin, and the current workspace
  and contracts ownership.
• The signed-out shell uses a minimal public connection/auth-recovery status. The
  detailed /api/v1/runtime response remains authenticated.
• The sign-in card may show an email claim, but the raw OIDC subject stays server-side;
  the existing opaque account key continues to separate browser-local data.
• Deployment-managed settings and configured-skill management stay read-only until a
  separate approved write contract exists.
• The Labs demo is a separate later item and does not gate real chat parity.

Implementation map

• Foundation and shell: Studio appearance: design tokens, palettes, typography, and shared controls #1843, Studio shell: navigation, search, error pages, and installable app assets #1844, Studio sign-in and recovery: OIDC popup, public status, and banners #1845.
• Settings and reference: Studio settings and About: section routes, provider detail, and shortcuts #1846.
• Chat: Studio chat: transcript, composer, and live-session layout #1847, Studio chat: inline approvals, plan review, and Escape behavior #1848, Studio chat: live subagent, parallel, and team activity #1849, Studio chat: minimap, side panels, and session inspection #1850, Studio chat: browse MCP inventory and insert into a draft #1851.
• Schedules: Studio schedules: list, editor dialogs, detail, and run history #1852.
• Skills, memory, and learning: Studio skills: inventory, detail pages, and learned-skill review #1853, Studio memory: stores, facts, detail, and consolidation #1854, Studio learning: proposal queue, evidence, and chat reflection #1855.
• Optional demo: Studio Labs: local demo chat and mock Projects tour #1856.

The existing #1776 track owns Playwright infrastructure and web test gaps; #1775 owns
agent conventions. Neither is re-created as a child of #1736. Implementation uses independent PRs targeting main; this issue does not require a
stack or an aggregate preview PR. Each PR carries desktop/mobile and interaction evidence
for maintainer review. After the core changes merge, run one final whole-app review on
main across navigation, auth/recovery, chat, schedules, skills, memory, learning,
responsive layout, and accessibility. Record and fix gaps before closing this review
issue. #1856 is a later, non-blocking demo item.

[samuv]

#1843 appearance foundation review evidence

Implementation candidate: #1873. The Plan / Interface PR is #1861; this review is for the stacked implementation, with maintainer visual and keyboard review still pending. The evidence below comes from the built Studio page under the existing CSP and uses the frozen 2026-09-24 palette baseline. It does not introduce an external design-system package or change ADR 0351's browser/BFF boundary.

Shared control inventory

Disposition	Controls	Result
Reused and normalized	Button, Input, Textarea, Badge, Card, Dialog, AlertDialog, DropdownMenu, Sheet, Switch, Tooltip, Kbd	Semantic colors, 1px control boundaries, 500px mobile scale, and visible keyboard focus. Public exports and Button variants/sizes stay intact.
Moved and repaired	OptionField from settings to components/ui/option-field.tsx	Same label, options, value, onChange and OptionItem contract. Radio dropdown at ≥500px; native-radio bottom sheet below 500px.
Added locally	Decorative paletteSwatch for the Appearance picker	Swatches are hidden from the accessibility tree; labels and descriptions name each choice.
Left to dependent issues	#1844 search command; #1846 settings table, tabs, and section-specific selectors	Both consume these semantic tokens and the shared appearance API.

The public browser API is useTheme() (light, dark, system) and usePalette() (default, aztec, mono, solar). OptionField is available for #1846; shell/nav tokens are available for #1844. The Default palette remains Stacklok green; there is no deployment palette override.

Contrast corrections to the frozen colors

Normal text is checked at 4.5:1. Interactive icons, focus indicators, and required control boundaries are checked at 3:1. The computed-color report covers the start, middle, and end of every shell gradient in all eight palette/theme pairs and finds zero failures. The weakest measured boundary is 3.11:1; the weakest measured shell text is 4.60:1. Values below are the intentional deviations; all other named-palette values stay at the frozen baseline.

Palette / mode	Corrected role: frozen → implemented
Default / light	--nav-search-border: #6e807d → #a5b0ae; --nav-search-text: #b4c0c1 → #cbd4d4
Default / dark	--nav-search-border: #6e807d → #728481
Aztec / light	--nav-icon: #8a998f → #aeb9b2; --nav-search-border: #4b6a60 → #aab9b4; --nav-search-text: #b7c4bd → #d7deda
Aztec / dark	--btn-primary: #12866f → #12846d; --nav-search-border: #3d5a50 → #71877f
Mono / light	--nav-search-border: #71717a → #85858d
Mono / dark	--nav-search-border: #4a4a4a → #727272
Solar / light	--btn-primary: #9a7300 → #946e00; --shell-gradient-start: #a77b0a → #775707; --nav-search-border: #a8925a → #c0b188
Solar / dark	--nav-search-border: #6b5a2a → #918561

The base-role corrections are --ring to #6b6b75 (light) / #a0a0a0 (dark), light --warning to hsl(35 92% 34%), and dark --destructive-foreground to #18181b. New --control-border uses #83838a (light) / #8c8c8c (dark). The shell/search focus ring now uses solid --nav-search-text, and the keycap label uses the white foreground role. The full contrast report includes badge, banner, and status-tint checks.

Rendered matrix

Each Appearance screenshot includes the shell and form. Each dialog/list screenshot shows the same appearance with search open and two local page results. Widths are 1280px desktop and 499px mobile. All 16 combinations returned HTTP 200, had no horizontal page overflow, loaded Inter and Merriweather from the same origin, and made no external font or asset requests. Computed roles and request results accompany the images.

Palette	Mode	Desktop appearance	Desktop dialog/list	Mobile appearance	Mobile dialog/list
Default	Light	View	View	View	View
Default	Dark	View	View	View	View
Aztec	Light	View	View	View	View
Aztec	Dark	View	View	View	View
Mono	Light	View	View	View	View
Mono	Dark	View	View	View	View
Solar	Light	View	View	View	View
Solar	Dark	View	View	View	View

For color comparisons, the eight frozen-value renders use the uncorrected roles against the matching desktop Appearance screenshots above. They are named <palette>-<mode>-baseline.png. The same directory contains desktop dropdown and mobile sheet focus captures.

Keyboard and persistence walkthrough

At 500px, ArrowDown opens the palette radio menu; End focuses Solar, Enter selects it, and focus returns to the trigger. Home/Arrow/Enter also changed System to Dark. At 499px, Enter opens the sheet, native radio selection changes the palette, Escape closes it, and both paths restore trigger focus. Resizing across 499/500 closes the prior surface without clipping or opening a second one. The 36 recorded browser checks also cover light/dark reload, cross-tab updates and storage clear, system-color changes, in-memory choice after storage denial, a safe default on denied-storage reload, and temporary transition suppression. The first-paint record shows root theme, palette, and UI scale while the stylesheet response is held. Rendered focus styles cover 16 light/dark keyboard-focus points, including Switch and Input after their focus-ring transition. Button icon sizing confirms a bare icon is 20px at 499px while an explicit larger icon retains its rem-scaled size. Rendered Shiki tokens keep each theme's syntax colors across all four palettes. This is implementation evidence for maintainers to review; it is not a claim that the review has already happened.