Studio: align the UI with the design prototype (prototype is the UI source of truth) #2210

User story

As a designer, I want the Studio UI I designed in stacklok/mecatl-prototypes to reach production without being redone by hand. As an engineer, I want one clear source of truth for how Studio looks, so we stop building the same screens twice.

Why

Studio (apps/) was forked on 2026-09-23 from the prototype's main as of about 2026-09-16. The designer's stack, prototypes #41–#48 (the same content as #40), started on 2026-09-21, after the fork. Since then the two codebases have grown in parallel with no agreed source of truth:

• Almost no file is byte-identical between them.
• Studio rebuilt surfaces issue by issue with custom controls.
• The prototype carries the shadcn/Radix design system and the full UX.

Both use the same architecture (Hono BFF, Vite/React SPA, Zod contracts, hey-api/TanStack Query), so we can converge without a rewrite.

Focus

This story is about design and UX only: bringing the visual design, components, layout, interaction, and copy from the prototype stack (prototypes #41–#47) into Studio.

The prototype's own architecture and tooling work is out of scope. That covers its BFF and server changes, the e2e fixture daemon, the sync tool, the convention tests, security headers, and configuration. Studio's architecture stays as it is.

Decision

• The prototype (stack/08-tooling) is the source of truth for UI: components, layout, interaction, and copy.
• Studio stays the source of truth for everything under the UI:
  • the BFF and contracts;
  • the published SDK (0.4.0);
  • security: CSRF, host guard, rate limits, CSP, and auth recovery with the popup;
  • approval and plan semantics: the verdict ledger, and exact plan-ask control with a 409 when the ask is stale;
  • the WCAG contrast tokens: --control-border, the solid ring, and the warning retunes.
• Port, don't transplant. Copy prototype files as close to verbatim as possible, then adapt them to Studio's contracts, tests, and lint rules. Each area lands as its own reviewable PR, with desktop and mobile before/after screenshots.
• This supersedes Studio design review and parity tracking #1779's "keep the existing local controls and tokens for this batch" decision for UI work.

Not ported (UX-adjacent behaviour Studio deliberately does differently)

• Schedule rename done as create-then-delete (see Studio schedules: stable identity and user-visible rename #2145).
• The prototype's theme, palette, and preference storage modules. Changing them would orphan saved user settings; the look is ported, the storage is not.
• The prototype's session-level plan approval. Studio's exact plan-ask control stays; only the card is re-skinned.

Out of scope for now

• Feature flags, the Labs section, and the mock demo tour (Studio Labs: local demo chat and mock Projects tour #1856).
• Settings write paths and configured-skill management (Studio skills: manage configured skills (create, edit, disable, delete) #2185).
• Moving primitives into a shared Stacklok UI package.
• The prototype's architecture and tooling (see Focus).

Phases

1. Foundation: primitives, shared UI hooks, shell, and search.
2. Feature areas: MCP, settings, schedules, knowledge, then chat last.
3. Cross-cutting: the accessibility and 500px sweep.

Sub-issues are attached below.

Done when

• Every surface matches the prototype's components and layout. Any intentional deviation is recorded in its sub-issue.
• task studio:check and the browser journeys pass on each PR.
• The designer has reviewed each area against the prototype.