Repository navigation
Studio design review and parity tracking #1779
Description
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/runtimeresponse 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.
Activity
[-]Studio design alignment: token and component inventory, surface-by-surface re-skin[/-][+]Studio design alignment with James's prototypes: UX, UI, components, colors, CSS[/+][-]Studio design alignment with James's prototypes: UX, UI, components, colors, CSS[/-][+]Studio design review and parity tracking[/+]samuv commentedon Sep 24, 2026
#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
OptionFieldfrom settings tocomponents/ui/option-field.tsxlabel,options,value,onChangeandOptionItemcontract. Radio dropdown at ≥500px; native-radio bottom sheet below 500px.paletteSwatchfor the Appearance pickerThe public browser API is
useTheme()(light,dark,system) andusePalette()(default,aztec,mono,solar).OptionFieldis 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.
--nav-search-border:#6e807d→#a5b0ae;--nav-search-text:#b4c0c1→#cbd4d4--nav-search-border:#6e807d→#728481--nav-icon:#8a998f→#aeb9b2;--nav-search-border:#4b6a60→#aab9b4;--nav-search-text:#b7c4bd→#d7deda--btn-primary:#12866f→#12846d;--nav-search-border:#3d5a50→#71877f--nav-search-border:#71717a→#85858d--nav-search-border:#4a4a4a→#727272--btn-primary:#9a7300→#946e00;--shell-gradient-start:#a77b0a→#775707;--nav-search-border:#a8925a→#c0b188--nav-search-border:#6b5a2a→#918561The base-role corrections are
--ringto#6b6b75(light) /#a0a0a0(dark), light--warningtohsl(35 92% 34%), and dark--destructive-foregroundto#18181b. New--control-borderuses#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.
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.
peppescg commentedon Oct 8, 2026
For UI work, #2210 supersedes this issue's "keep the existing local controls and tokens" decision. The design prototype (
stacklok/mecatl-prototypes,stack/08-tooling) is now the source of truth for Studio's UI and UX. Studio's WCAG contrast tokens, BFF, and approval semantics stay as they are. #1851, #1852, #1854 and #1855 now sit under #2210.