Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

fix(ui): rebuild onboarding to the approved design and suspend its motion off screen (#2028)

Max78db7eae5c9d
diff --git a/docs/plans/2026-09-17-onboarding-design-fidelity.md b/docs/plans/2026-09-17-onboarding-design-fidelity.md
new file mode 100644
index 000000000..b90d94f16
--- /dev/null
+++ b/docs/plans/2026-09-17-onboarding-design-fidelity.md
@@ -0,0 +1,384 @@
+# Onboarding design fidelity repair — issue #2017
+
+PR #2015 merged successfully but did not faithfully reproduce the approved Welcome and assistant-setup design. The owner rejected the visual fidelity on 2026-09-17 and explicitly identified the existing animated Show Page as the implementation reference. At 16:55 the owner additionally required the designed widths and adaptation to different screens.
+
+## Authority and scope
+
+- Static appearance, copy, dimensions, and state presentation: `avibe-docs/design_desktop.pen`, read only through Pencil. The latest design wins if the older prototype differs.
+- Welcome animation reference: https://max-app.avibe.bot/p/SM2vv4wGlM4/ (existing source is available locally; reuse its authored sequence and visual details rather than approximating it).
+- Fix forward from current `master` after #2015. This is the visual correction of #2010. Keep existing logo assets, shared React Web/Desktop ownership, and existing setup/auth/config behavior.
+- The separate #2011 authentication/readiness and #2012 Workbench/General issues retain their behavior scope. #2013 native desktop integration remains later. No new auth model, fabricated connected state, native window controls in Web, service restart, or production-state testing.
+
+## Confirmed gaps in the merged source
+
+- Document and code content were flattened into generic bars; document paragraphs/footer and code indentation/multiple segments are missing. Reveal, completion, and check-mark timing differ from the reference.
+- The return wire loses its rounded route, ports, glow, and traveling pulse treatment. Return caption does not change with the cycle. PM content is reset at the summary phase.
+- Theme fills/borders/shadows and internal spacing were approximated. A 240x228 outer card alone does not establish design fidelity.
+- Narrow screens switch the collaborative diagram into a long vertical stack and hide the electric feedback loop, unlike the provided responsive prototype.
+- Page/container widths, header composition, access-tile geometry, and setup-row alignment require an explicit measured comparison, including their interaction states.
+
+## Acceptance contract
+
+1. Every shared surface delivered by #2010 is compared to its corresponding final design state at the same effective content viewport. Record native-titlebar exclusion explicitly, retaining the designed Web content geometry. No arbitrary max-width, global zoom, or screenshot-only CSS may stand in for the designed layout.
+2. At the desktop reference, collaboration is 880x272, each card 240x228, access area 640 wide, primary Welcome action 144x44, and assistant rows 880x88. **Superseded on 2026-09-17 by the owner's accepted 1104 cap — see "Accepted width" below; the frames' 880 numbers remain the source proportion.** Read precise text, spacing, radii, borders, fills and effects from Pencil, including Light values. Larger viewports preserve designed component widths and center the content. Smaller/shorter screens adapt without clipping, horizontal overflow, overlapping labels, disconnected wires, or unreachable controls; keep the collaborative sequence legible.
+3. Welcome reproduces the authored 8.9-second loop: PM 0–1.5s; first handoff 1.5–2.25s; Codex 2.25–3.75s; second handoff 3.75–4.5s; tests 4.5–6s; return 6–7s; summary 7–8.9s. Source remains active in transit; destination activates on arrival. Document/code reveal, sequential test ticks, 850ms progress circle, 300ms hinge check, 250ms caption fade, wire ports/glow, and return caption follow the design/reference. Completed PM work stays complete during summary.
+4. ~~Pause/replay synchronize all animated layers~~ — **superseded on 2026-09-17 18:26 by the owner: the design has no playback controls, so none ship.** Hidden/offscreen content suspends nonessential work; reduced motion gives a complete static narrative. Access-tile interaction and emphasis follow the reference and preserve keyboard use. See "Playback controls removed" below.
+5. Dark/Light and Chinese/English use the same faithful component geometry. There is no separate Light English frame: combine the approved English copy and Light visual specification. Existing logos remain unchanged. Existing configuration, detection, installation, synchronization, navigation, and recovery invariants stay intact.
+6. Evidence includes design exports, actual product screenshots, a same-size side-by-side or overlay comparison, measured geometry, and captured motion phases. Inspect desktop, intermediate, wide, narrow and short viewports; the representative matrix includes 1200x800, 1440x900, 1024x768, 768x1024, 390x844 and 320x568. A test count or a no-overflow assertion alone is not visual acceptance.
+7. Before PR delivery, PM independently checks rendered fidelity and one consuming regression test. Run focused behavior/motion/i18n tests, UI build/lint, theme/catalog checks and the scoped Impeccable detector. Changes stay hermetic with mocked APIs; never claim live OAuth or real installation coverage from mocks.
+
+## Reference frames
+
+Welcome: `bi8Au`, `J0qaZ`, `P8iLm0`.
+Setup: `i3vw9`, `lm7mN`, `ktRgC`; hover `mK2JX`, `ZaXoW`, `X7N2Z`; awaiting connection `ICidc`, `S3mLYc`, `HR3ps`; upgrade `I9Q8VD`, `pHiuw`, `QPdWU`; connected `F8RLgR`, `r1IQ0B`, `xNmhX`.
+
+Installed/connection controls that depend on #2011 must be explicitly recorded as that issue's outstanding behavior, never presented as visually accepted by this correction. This issue restores the reachable #2010 surface and existing presentation props without inventing readiness.
+
+## Delivery
+
+One isolated task worktree and a non-draft PR to `master`; owner visual acceptance is required before declaring design fidelity complete. Exact-head Codex pass, all required CI green, zero unresolved threads, and review-loop circuit breaker remain mandatory. **Do not manually post `@codex review`: cyhhao triggers automatically; report any verified automation gap.** No automatic merge; the prior authorization applied to #2015 only.
+
+
+## Execution contract
+
+Owner session: `sestqz5wvu5ty`. Branch: `fix/onboarding-design-fidelity`.
+Baseline: `0d3e44de245e109b3e5e2dd98ce85c9b5e9a21f4` (latest origin/master at dispatch).
+This plan supersedes the visual acceptance claim for merged #2010, not the deferred behavior boundaries of #2011–#2013. Implementation is authorized by the owner's correction; no repeat permission request is needed.
+
+Source evidence (read-only):
+- `/Users/max/workspace/ai/avibe/avibe-docs/design_desktop.pen`
+- `/Users/max/.avibe/show/ses36vg559de2/src/pages/index.tsx`
+- `/Users/max/.avibe/show/ses36vg559de2/src/welcome.css`
+- `/tmp/onboarding-visual-repair/frames.json` and `design/` — freshly exported by Pencil on 2026-09-17 around 17:00. Check live source if a conflicting change is observed.
+- `/tmp/issue2010-pencil.py` — working read-only stdio helper; initialize, notification, then 2s client registration delay. `execute` may use only Get/Print/Export/TakeScreenshot for this task. Do not parse or save the .pen raw file.
+
+The prototype is an animation reference, not authority for stale product layout: the latest Pencil Welcome has no centered extra brand row, and its access area differs from the prototype's horizontal padding. Preserve existing logo assets wherever used; do not introduce the prototype Radio placeholder as a new Avibe logo. Shared Web omits simulated macOS window controls; compare the shared content rectangle explicitly instead of shifting all measurements silently.
+
+### Animation origin session and precedence
+
+On 2026-09-17 17:10 the owner named Session `ses36vg559de2` as the animation origin
+("引导页动画实现在 ... 这个会话,你去参照"). Its local source at
+`/Users/max/.avibe/show/ses36vg559de2/src/` is that Session's implementation and is
+already the animation reference in this plan. Precedence, highest first:
+
+1. Latest `design_desktop.pen` frames — static geometry, copy, fills, borders, radii, state presentation.
+2. Session `ses36vg559de2` source — motion sequence, skeleton shapes, glyph and pulse behavior, calibrated glow.
+3. Older prototype layout — superseded wherever 1 or 2 disagree.
+
+Owner decisions carried from that Session's history (`/tmp/onboarding-visual-repair/reference-owner-decisions.json`,
+96 messages; motion refinements in `reference-session.json`):
+
+- Horizontal three-card PM/developer/tester story with authored document and code skeletons,
+ progressive line reveal, and ordered test checks.
+- Final durations: each work step <=1.5s, horizontal pulse 0.75s, return 1s, whole loop 8.9s.
+ Earlier 12s / 2s / uniform-1s versions are superseded.
+- Each handoff pulse travels once and disappears on arrival; no static arrows. The destination
+ highlights and begins internal work only after the pulse lands; the source stays active in transit.
+- The working glyph is a drawn green ring, not the earlier solid dot with a bubbling halo. The same
+ ring stays mounted through completion, closes, then the check grows elastically from its hinge
+ toward both ends. The ring is about 12px inside a 14px glyph. The status caption fades over 250ms
+ without interrupting the ring.
+- The active card carries a visible exterior green glow; an inward or too-subtle shadow was rejected.
+ Use the browser-calibrated glow, not a naive transfer of Pencil's shadow spread. The Light pulse
+ stays light mint rather than turning dark.
+- Six access tiles use the actual product icons with Avibe App first. Hover scales the icon to 1.18
+ and fills the tile at about half the border's opacity; idle randomized emphasis pauses on pointer
+ entry and keyboard use stays intact. No outer wrapper border. The CTA itself stays still and only
+ its arrow moves 4px right.
+- The 2026-09-17 design removes the header and centered brand logos from the guidance screens
+ ("这些引导页的logo都去掉") and widens the six access tiles so their outer edges align with the
+ left and right vertical legs of the return wire ("左右侧和左右的这2条线对齐"). Existing product
+ logo assets stay wherever a logo still belongs.
+- The setup heading matches the Welcome heading in size, style, and position; setup content matches
+ Welcome's width; row hover uses the Welcome glow.
+- In Light, green-button text and icons are both white.
+
+Unrelated logo exploration, desktop-shell implementation, and historical manual review triggers from
+that Session are out of scope. The owner's no-manual-`@codex` rule still applies.
+
+### Width and screen adaptation
+
+Owner on 2026-09-17 17:14: "你要考虑不同大小屏幕的适配,是固定宽度还是?". The answer is a
+capped fluid layout with a responsive internal arrangement — not a globally fixed 1200px page and
+not a transform/zoom scale-down.
+
+- 1200x800 is the design reference viewport, not a forced window size. Wider monitors gain
+ surrounding whitespace; the cards never stretch to fill them.
+- Below the cap, containers are `width:100%` with that max-width plus explicit page
+ gutters (40px desktop, 24px tablet, 16px phone: 390 -> 358 usable, 320 -> 288 usable). No
+ page-level min-width, so there is no horizontal overflow. The card grid uses percentage tracks
+ (27.272727% with space-between), so card width, handoff gaps, and the stretched wire viewBox stay
+ proportional at every container width without a separate rule per size.
+- Intermediate widths adjust gaps and spacing before shrinking content. At phone widths the
+ collaboration keeps its compact horizontal narrative, with wires and ports still attached to real
+ card geometry. Card-internal labels wrap or stack and the diagram grows taller rather than
+ shrinking text to an unreadable size; the caption stays at or above 11px instead of the
+ prototype's 7px.
+- Access tiles drop from three columns to two on narrow screens with comfortable targets. Assistant
+ setup rows reflow status and actions onto another line, and the desktop 88px row height becomes
+ content-driven on small screens.
+- Short windows scroll naturally and keep the primary action reachable; no `overflow:hidden`
+ clipping and no global scale-down. Content taller than the viewport is never cut off above the
+ fold. **Corrected 2026-09-17 18:36: the welcome is vertically centred and the setup is
+ top-anchored, because the frames anchor them differently — see "Vertical rhythm" below.**
+
+If a full label cannot stay readable at the minimum width, report the concrete constraint and the
+smallest layout adaptation rather than hiding information or treating no-overflow as a pass.
+
+### Accepted width: 1104
+
+Owner on 2026-09-17 17:38: "用1104". This accepts PM's recommendation and supersedes both the
+frames' 880 and the unaccepted 1240 candidate. The frames stay the source of proportion; 1104 is
+the cap the whole composition is drawn at.
+
+- One shared `--ob-content-w: 1104px` caps the header, the Welcome story and the assistant rows,
+ so header and body can never drift apart.
+- Everything else is that cap times its authored ratio to 880, never a re-typed number: access area
+ `640/880` -> 802.9, cards `27.272727%` -> 301.1 with 100.4 of handoff space, diagram
+ `880:272` -> 1104x341.2, cards `228/272` of the diagram -> 286.0.
+- The diagram is sized from its own width (`aspect-ratio`), not from the cap, so the proportion
+ holds at every width between the gutters and the cap and the stretched `880x272` viewBox keeps
+ every port on its card edge. Widening the cap alone would have detached the wires.
+- Card interiors are drawn in design units (`--ob-u: 100cqw / 880`): padding, skeleton rhythm, bar
+ and check sizes grow with the card, while text, icons and controls keep their authored sizes. A
+ card a quarter taller must not read as a zoomed screenshot, and must not leave a hole under its
+ skeleton either.
+- Assistant rows widen to 1104; their 88 height stays because the row's contents fit it, and it is
+ a `min-height` on the row itself (border included), not a multiplication. Everything inside the
+ row keeps its authored size and offset, so the extra width lands in the identity column only.
+- Below 960 the bands keep their hand-chosen diagram height and the authored interior rhythm.
+
+### Vertical rhythm
+
+The design's 1200x800 frames include the native 44px titlebar, so the web content box they describe
+is 1200x756.
+
+**Corrected 2026-09-17 18:24 (PM, from the live file).** Both frames show the heading block 65px
+below the content edge, but only one of them *specifies* it. `JuwcG` and `KIxnF` centre the welcome
+inside their frame, so its 65 is a RESULT of that frame's height; `IWQi6` tops the setup out at its
+own 64.5 padding, so that 65 is the position itself. The product reproduces the setup's number as
+20px shell padding plus the 45px language bar, and centres the welcome in what is left. A test that
+pinned the welcome's y to 65 was asserting the one window height where the two happen to agree, and
+has been replaced by a centring assertion plus the setup's own fixed top.
+
+Centring is `align-self: center` inside a `flex: 1 0 auto` content box, which is what keeps a
+composition taller than the window from being pushed off the top: the box grows to its content, the
+slack to share becomes zero, and the shell scrolls from the content edge.
+
+Measured from the frames rather than the exports, both screens run one rhythm from that edge:
+
+- Welcome (`bi8Au`): heading 79, 24, collaboration 880x272, 24, access 640x160, 24, action 144x44,
+ then 64 of slack. The heading is a 34/1.35 title, a 10 gap and a 14/1.57 subtitle; a browser
+ stacks the same type to 77.9 because the design rounds each text box up on its own.
+- Setup (`i3vw9`): the same heading block, 24, a 29 tall section bar, 12, then 88 tall rows on a
+ 100 pitch, 24, and a footer that spaces action, hint and Back by 10. Inside a row: a 44 well 20
+ from the outer edge, identity 16 further in, status and action against the opposite 20.
+- The setup frame's OUTER container starts at x=48 of the 1200 frame and is 1104 wide, but the
+ rows and content inside it are drawn at 880 like the welcome's. 1104 is therefore the design's
+ own outer container, not its content width; the content reaches it only by the owner's amendment,
+ and 48 is the gutter at which that cap is met.
+
+The amendment changes exactly one term of that rhythm: the collaboration is 341.2 rather than 272,
+so the welcome needs 781 of content height where the design needed 692. A 1200x800 desktop window
+has a 756 content box, so something has to give.
+
+**Corrected 2026-09-17 18:36 (PM).** It is not the spacing. There used to be a `max-height: 760px`
+band that took the 24 gaps to 16 and halved the access block's padding; it bought about 30px and
+spent the design's own composition to do it, at the reference's own frame size, where nothing was
+wrong. That band is deleted. Whitespace IS the composition, so a short window scrolls: the type,
+the icons, the buttons, the 24px gaps, the 88px assistant rows and their 12px spacing are identical
+at every height, and only width adapts.
+
+### 2026-09-17 18:23-18:36 repair disposition
+
+PM held the first repair before push and issued a bounded correction list; the owner overruled one
+part of it directly. This section is the source-backed disposition and replaces any earlier claim in
+this plan that contradicts it.
+
+#### Playback controls removed (owner, 18:26)
+
+"不需要暂停和播放按钮,设计图里都没有呀". Every user-facing pause / play / resume / replay control
+is gone, together with its reserved layout space, its state and handlers, and its copy and styles.
+No substitute control replaces it. The loop starts with the screen and owns itself.
+
+What stays is lifecycle only, because the browser — not the user — asks for it:
+
+- `useOnboardingMotion()` returns `running` from a reduced-motion preference, document visibility
+ and whether the composition is on screen. It has no setter and no UI.
+- A hidden tab stops both halves of the motion together: the React clock the cards are read from,
+ and the CSS animations the shimmer and the test ticks run on. Stopping only the first would leave
+ the second playing on unseen and reappearing mid-sweep.
+- Being scrolled out of sight stops the same two halves, because a visible document is only half
+ the question: on a short window the diagram sits entirely above the viewport while the user reads
+ the button below it. The hook observes the element each consumer attaches its ref to, so the story
+ and the access tiles suspend independently: both are normally on screen together at desktop sizes,
+ while a short or narrow window can give them different intersection. `threshold: 0` is the
+ reading the incumbent observer in `vault-chat-requests` takes, so any intersecting pixel counts
+ and a composition at the seam stays live instead of stuttering.
+- No restart machinery was built for the removed button. Resuming continues the same sweep.
+
+Manual pause/replay UI tests are deleted; the suite now asserts the *absence* of playback controls
+on both steps, and captures deterministic phases through test-owned time control rather than any
+shipped UI.
+
+**Defect found by the rendered-state assertion.** The `data-motion="paused"` rule lost on
+specificity to `.onboarding-collaboration-card[data-state="working"] .onboarding-skeleton::after`,
+whose `animation` shorthand resets play state to running — so the longest-running effect on the
+screen was the one the suspension never reached. Asserting the attribute would have passed. The rule
+now carries `!important`, for the same reason the reduced-motion block does: no authored rule should
+be able to out-specify "the tab is not being presented".
+
+#### The access block follows the actual diagram width
+
+The six tiles are drawn 640 wide on the diagram's own 880 box, so their outer edges land on the
+vertical legs of the return wire (the ports at x=120 and x=760). `.onboarding-access` is therefore
+`calc(100% * 640 / 880)` of the same box the diagram is sized from, not a number that happens to
+agree at the cap. It is asserted at 1440 / 1200 / 1100 / 1024 / 900 / 768 against the rendered port
+centres, because only a width derived from the real diagram holds at all of them.
+
+Documented exception, below 600: two columns of 640/880 of a phone would be about 200px of tiles
+inside a 360px screen, so the block takes the full content width and the tiles stay a readable
+target. This deliberately leaves the wire relation rather than following it into an unusable size.
+
+#### The active-card halo is one managed semantic token, themed through variables
+
+The reference's dark halo is a spread-less 28px mint at `#5BFFA060`; Light has its own tighter
+16/-4 at `#10B98170` over a `#10B98160` border. Both are now carried by one managed token,
+`--shadow-glow-onboarding-mint`, instead of approximated by stacking two rungs of the sized scale.
+
+Its per-theme parts are named runtime variables (`--onboarding-glow-blur`, `-spread`, `-alpha`)
+re-anchored beside the rest of each light palette. That shape is not decoration: `src/index.css`
+declares the token inside `@theme inline`, so Tailwind substitutes its VALUE into the utilities at
+build time and a later re-declaration of the token name would compile to nothing while looking
+correct in the file. `--brand-glow-blur` already uses this shape, and `assertInlineThemeTokensAreNotRedeclared`
+exists precisely to fail the other one. The hue needs no variable: `color-mix(in srgb, var(--mint) …)`
+already follows whichever mint the theme declares.
+
+The auditor was strengthened rather than widened. `glowScale.test.mjs` now resolves each rung
+through its own theme's declared numbers before asserting, so a themed blur is a number by
+assertion time — which let the CTA move from "themed blur, therefore unasserted" to pinned at 16
+(dark) and 20 (light), and let the new onboarding role be pinned in both themes. Four red probes
+confirm it bites: light CTA blur, light onboarding blur, light onboarding alpha, dark onboarding
+spread. No idle card or assistant row gained a drop shadow; the suite asserts idle cards carry
+`box-shadow: none` in both themes.
+
+#### Type, mobile identity, and button chrome
+
+- The live design's headline is 34/1.35/600 at **-1.6** tracking (`XKQOx`, `Igagh`, `hv9DA` agree),
+ shared by both steps and asserted from computed style.
+- Narrow adaptations are deliberate and recorded in the stylesheet where they are made: 30/-1.4 at
+ 960 (the same -0.047em ratio), and 25/-0.8 at 600 — phones loosen rather than follow the ratio,
+ because tight tracking is exactly what costs legibility at that size.
+- Below 600 the three card footers use one explicit grid (logo, name, role, each on its own row)
+ with the name's box holding the two lines the longest of them needs. Free flex wrapping produced
+ a different arrangement per name length and left the three separators up to 21px apart. Nothing is
+ truncated, scaled globally, or dropped to the prototype's 7px; both lines of a wrapped name show.
+ Asserted at 320 and 390 in EN and ZH and in the 768 band, from real bounding boxes: equal status
+ y/height, equal identity y/height, no clipped or ellipsised label, role type at or above 10px.
+- Re-scan is outlined (`n4ATm` / `H8gj7`); install and configure keep a visible themed border and
+ surface; primary actions rest flat on the designed theme fill with its designed text colour. No
+ global button recipe was rewritten and no darker global primary palette was adopted.
+
+#### Skeletons are audited against native coordinates
+
+All three are written from their own nodes and the numbers are recorded beside the rules:
+`h5qtNn` (17 above the heading, then 12 / 8 / 14 / 7 / 7 between six lines, 14 below the last),
+`u3bGM` (six 11-tall rows on a 16 pitch, 14 below the box top), `xyNG1` (four 12-tall rows on a 23
+pitch, 17 below the box top — fewer rows, so this skeleton ends higher; the design's own asymmetry,
+not slack). The extra card height the 1104 cap creates is allocated by reserving each end's authored
+share in design units (17.56 status + 149.3 skeleton + 18.8 + 55.2 identity = 240.9 of content), so
+the three separators align by construction and the surplus cannot pool under the last bar.
+Typography and icons keep their authored sizes. No document footer or test-result strip was added.
+
+#### Source-approved, left alone
+
+The dark browser shadow stays as drawn (the native -17 spread is not copied), the return height is
+correct, the 2s access emphasis is authored interaction and is not erased to match a static still,
+existing logo assets and `PlatformIcon` are untouched, an idle Codex card is authored, the shimmer
+is authored, and dual-card glow in a settled still is a comparison artefact of holding every effect
+at one time rather than leakage.
+
+Two observations from the 21:40 read-only visual pass are recorded as non-blocking rather than
+fixed: the English testing caption takes three lines at 320 — the footer and card baselines stay
+aligned and every word is readable, so wrapping is preferred to shrinking it — and the optical
+top/bottom difference at 768 is explained by the native header's own space, so no redesign follows.
+
+#### Evidence claims
+
+- Settled stills (every CSS effect held past its end) are the only images compared against a static
+ frame; they are labelled as such. The normal-speed evidence is a separate recorded run with no
+ clock control at all, sampling what the page actually draws across a full loop and across a
+ hide/show.
+- `ThemeProvider` is checked for real: System mode sets no `data-theme` and follows an emulated OS
+ switch live, and a stored explicit preference survives the OS moving in either direction and a
+ reload.
+- The fixture stays hermetic: a deny-by-default route records every non-GET or off-origin request
+ and each test asserts that list is empty. No local service, no Incus runner, and no OAuth or
+ install was ever performed — the assistants render an installed, permitted runtime because the
+ fixture answers those reads, which is a rendering claim and not a working-integration one.
+
+**Capture clock ownership, corrected 2026-09-17 21:52.** `page.clock.install()` replaces the timer
+functions but leaves the clock advancing with real time — measured directly: 38 ticks of a 16ms
+interval in 600ms of wall time. Only `pauseAt` holds it. Every "settled" still therefore landed
+wherever wall-clock time had carried the story, which is how a dark and a light capture of the same
+size ended up drawing different cards. `openOnboarding` now pauses at a fixed instant, after which
+only `freezeAt` moves it; each still names its phase in its filename and the capture asserts the
+rendered states are that phase's. This was found because the new offscreen test failed on it, not to
+improve a claim.
+
+Two limitations stand in the batch as it exists:
+
+- `welcome-design-frame-1200x756-codex-working.png` is a VIEWPORT CROP, not a whole composition: at
+ 756 the primary action is below the fold. It proves matching in-view geometry only. Scrolling is
+ the accepted outcome and the button is reachable; the companion `…-cta-…` still shows it scrolled
+ to, and a second companion at 390x300 comes from the offscreen test.
+- Images produced before the clock fix are not an exact-phase cross-theme pair, whatever their
+ filename said. No deterministic same-phase A/B may be claimed for that batch. The batch shipped
+ with this change is regenerated under the paused clock, where the phase is exact by construction.
+
+#### The 360 slot is the assistant block (PM, 21:38)
+
+Item 3's "minimum 360px slot" is `.onboarding-assistants`, the region native `sNs1V` names, and it
+already carries `min-height: 360px`. An earlier note in this plan added up 252 and 348 from the
+blocks *around* it and concluded the number did not resolve; those sums never measured the slot's
+own minimum and are withdrawn. No implementation change followed — the geometry case now asserts the
+slot directly (computed `min-height` 360, rendered height at least 360), together with the 24 below
+it and the 52 from the last row to the button. Measuring both gaps is what shows the 52 comes from
+the slot's spare height plus the 24, rather than from a margin tuned to match it.
+
+### Follow-on boundary (not this patch)
+
+The owner's 17:49 desktop request (no top navigation, System-default theme switching) belongs to
+issues #2012 and #2013. This patch preserves the existing `ThemeProvider` semantics (System default,
+stored manual preference, shared setter) and the Web language entry in the onboarding header, and
+adds no desktop detection.
+
+### Ownership
+
+Single UI implementation lane owns `ui/src/components/onboarding/*`, `ui/src/components/steps/Welcome.tsx`, presentation-only edits in `steps/AgentDetection.tsx` and `Wizard.tsx`, directly related tests, only relevant `onboarding.*` keys in `ui/src/i18n/en.json` and `zh.json`, and this plan plus a short status correction to the existing shared plan. Keep detection/install/provider reconciliation, Back/Continue completion flow, and auth semantics intact. Reuse existing primitives/icons; component-scoped theme variables may encode exact approved design values without changing the global theme. Broader tokens/primitive or behavior changes require PM scope diagnosis before editing.
+
+No-touch: primary checkout, old shared-onboarding worktree, other task branches/worktrees, design file, existing Show Page, native desktop, Python/API/persistent schema, credentials, runtime service, unrelated i18n, and global Workbench/Settings. PM may edit this plan before dispatch; after dispatch the lane is the sole writer until hand-back.
+
+### Implementation and evidence
+
+- Audit incumbent at this baseline against complete exported state set. Record residual #2011 controls accurately. Fix all in-scope visual drift, not only the obvious animation.
+- Port the authored sequence and skeleton/line/check shapes into the existing React components. Adapt imports/i18n/semantic theme ownership; avoid importing the Show runtime or introducing parallel controllers/dependencies.
+- Desktop width is constrained by design, not by available monitor width. On narrow screens preserve the pulse's source/destination connections through actual component sizing; do not solve overflow by discarding the narrative.
+- Build a hermetic browser fixture for the actual product entry with mocked network and isolated browser state. Explicitly deny unmatched write-capable requests. Never connect to the running local service or call the Incus runner. No real auth/install claim.
+- Capture design, before and after at the same content viewport and freeze the same timeline phase (reference is PM complete, Codex working, tests waiting); record crop/native-titlebar rules. Capture each phase and a representative full loop, plus hidden/reduced motion — ~~pause/replay~~ superseded 18:26, there are no playback controls to capture. Automated bounding rectangles supplement screenshots, not replace them.
+- Test responsive invariants over wide/intermediate/narrow/short sizes; test Chinese/English and light/dark, preserve System mode. At 1200x800 do not inherit the prototype's preview-stage breakpoint that shrinks the cards merely because height <=850; the actual design has 240x228 cards there.
+- Before opening a PR, deliver a concrete diff, local verification and screenshot/motion evidence for PM spot-check. No new product-direction approval is required. PM checks fidelity and consumer regressions before the first push.
+- After the reviewed patch is ready, create PR with `Closes #2017`, base master, include scenario IDs and evidence/residual checks. Immediately notify PM with PR/head so an independent PM Watch can be armed; keep one durable lane combined PR/CI Watch. Never manually trigger Codex. Review/CI follow-up uses the normal circuit breaker.
+
+### Tasks
+
+- [x] Issue created and title/body read back.
+- [x] Read existing Show Page source and latest Pencil frames.
+- [x] Isolated worktree created from latest master.
+- [x] Complete source-to-render difference table and fix shared visuals.
+- [x] Complete same-viewport screenshot, motion and responsive evidence.
+- [x] Bounded repair of the 18:23-18:36 disposition, recorded above.
+- [x] Offscreen suspension, the 360 slot assertion, and the capture clock fix (PM 21:38/21:40).
+- [ ] PM independent pre-push spot-check.
+- [ ] PR, exact-head review, zero unresolved threads, all required CI green.
+- [ ] Owner visual acceptance; merge requires a fresh explicit instruction.
diff --git a/ui/e2e/onboarding-fidelity/fixture.html b/ui/e2e/onboarding-fidelity/fixture.html
new file mode 100644
index 000000000..dfdaac5cc
--- /dev/null
+++ b/ui/e2e/onboarding-fidelity/fixture.html
@@ -0,0 +1,2 @@
+<!doctype html>
+<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Onboarding fidelity fixture</title></head><body><div id="root"></div><script type="module" src="./fixture.tsx"></script></body></html>
diff --git a/ui/e2e/onboarding-fidelity/fixture.tsx b/ui/e2e/onboarding-fidelity/fixture.tsx
new file mode 100644
index 000000000..ee169c8a5
--- /dev/null
+++ b/ui/e2e/onboarding-fidelity/fixture.tsx
@@ -0,0 +1,39 @@
+// Mounts the product's own Wizard — the real component that renders the Welcome
+// and assistant-setup screens — inside the real providers. Nothing here restates
+// onboarding layout or behaviour: the whole point is that the browser measures
+// the shipped component tree. Every request is answered by the spec's routes, so
+// the fixture never reaches a running service and never writes anything.
+import { createRoot } from 'react-dom/client';
+import { createInstance } from 'i18next';
+import { I18nextProvider } from 'react-i18next';
+import en from '../../src/i18n/en.json';
+import zh from '../../src/i18n/zh.json';
+import '../../src/index.css';
+import { ApiProvider } from '../../src/context/ApiContext';
+import { ThemeProvider } from '../../src/context/ThemeProvider';
+import { ToastProvider } from '../../src/context/ToastProvider';
+import { Wizard } from '../../src/components/Wizard';
+
+// The product's own ThemeProvider, reading the same `?theme=` it reads in the app:
+// `dark` and `light` are explicit preferences, `system` follows the OS. Writing
+// `data-theme` here instead would have been the fixture theming itself, which cannot
+// show whether System-mode follow and preference preservation still work.
+const params = new URLSearchParams(location.search);
+const language = createInstance();
+await language.init({
+ lng: params.get('lang') ?? 'en',
+ resources: { en: { translation: en }, zh: { translation: zh } },
+ interpolation: { escapeValue: false },
+});
+
+createRoot(document.getElementById('root')!).render(
+ <I18nextProvider i18n={language}>
+ <ThemeProvider>
+ <ToastProvider>
+ <ApiProvider>
+ <Wizard />
+ </ApiProvider>
+ </ToastProvider>
+ </ThemeProvider>
+ </I18nextProvider>,
+);
diff --git a/ui/e2e/onboarding-fidelity/geometry.spec.ts b/ui/e2e/onboarding-fidelity/geometry.spec.ts
new file mode 100644
index 000000000..1ca914796
--- /dev/null
+++ b/ui/e2e/onboarding-fidelity/geometry.spec.ts
@@ -0,0 +1,681 @@
+import { expect, test, type Page } from '@playwright/test';
+import {
+ PHASES, VIEWPORTS, cssEffects, freezeAt, openOnboarding, openSetup, renderedPhase,
+ serveProduct, setDocumentHidden, settleEffects, size, storeThemePreference,
+} from './support';
+
+/**
+ * The 2026-09-17 design is a set of exact numbers, so this suite measures the shipped
+ * component in a browser instead of asserting that nothing overflows. Screenshots are
+ * written as artifacts from the same runs that make the assertions, so the evidence and
+ * the guard can never describe two different builds.
+ *
+ * Sizes: a Playwright viewport IS the web content box, so nothing is subtracted for
+ * chrome. The design's own 1200x800 frames include the native 44px titlebar above the
+ * web view, which makes the design's content box 1200x756 — that is the size to overlay
+ * a frame against (DESIGN_FRAME below). The dispatch's 1200x800 of effective content is
+ * the larger window that same content box needs, and is what the matrix captures.
+ *
+ * The owner accepted 1104 as the desktop content cap on 2026-09-17, superseding the
+ * frames' authored 880. Every number below is that decision applied to the frame's
+ * proportion (1104/880 = 1.2545...), not a re-measured design.
+ */
+const DESIGN_FRAME = { width: 1200, height: 756 };
+/**
+ * The one moment every still is taken at, carried into the filename so an artifact says
+ * which phase it is rather than leaving a reader to infer it. Since `openOnboarding`
+ * pauses the clock before the page loads, this is exact and not merely settled: the same
+ * phase draws the same cards across themes, languages and sizes, which is what makes a
+ * dark/light pair of one size a content A/B rather than two unrelated frames.
+ */
+const CAPTURE_PHASE = 'codex-working';
+const CAPTURE_STATES = ['complete', 'working', 'waiting'];
+/** 20px of shell padding plus the 45px language bar: the setup's authored top (IWQi6). */
+const SETUP_TOP = 65;
+
+const box = async (page: Page, selector: string, index = 0) => {
+ const rect = await page.locator(selector).nth(index).boundingBox();
+ if (!rect) throw new Error(`${selector} is not rendered`);
+ return rect;
+};
+
+/** Every match's real rect in one round trip — what "aligned" has to be measured from. */
+const boxes = (page: Page, selector: string) =>
+ page.locator(selector).evaluateAll((nodes) => nodes.map((node) => {
+ const rect = node.getBoundingClientRect();
+ return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+ }));
+
+const round = (value: number) => Math.round(value * 100) / 100;
+const spread = (values: number[]) => Math.max(...values) - Math.min(...values);
+
+test.describe('desktop reference geometry', () => {
+ test.use({ viewport: { width: 1200, height: 800 } });
+
+ test('welcome matches the accepted 1104 collaboration and 802.9 access spans', async ({ page }, info) => {
+ const denied = await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+
+ const collaboration = await box(page, '.onboarding-collaboration');
+ expect(round(collaboration.width)).toBe(1104);
+ expect(collaboration.height).toBeCloseTo(341.24, 1);
+ // Card size comes from a percentage track and the diagram's own width, so the
+ // proportion holds at every width; those ratios are not representable on the
+ // engine's 1/64px grid, so the numbers are met to within a sixty-fourth of a pixel.
+ for (let index = 0; index < 3; index += 1) {
+ const card = await box(page, '.onboarding-collaboration-card', index);
+ expect(card.width).toBeCloseTo(301.09, 1);
+ expect(card.height).toBeCloseTo(286.04, 1);
+ }
+ const [first, second, third] = await Promise.all([0, 1, 2].map((index) => box(page, '.onboarding-collaboration-card', index)));
+ expect(second.x - (first.x + first.width)).toBeCloseTo(100.36, 1);
+ expect(third.x - (second.x + second.width)).toBeCloseTo(100.36, 1);
+ // What has to be exact is that the wire endpoints sit on the card edges: both are
+ // driven by the same percentage basis, so a port can never drift off its card.
+ const port = await box(page, '.onboarding-port', 0);
+ expect(port.x + port.width / 2).toBeCloseTo(first.x + first.width, 1);
+
+ const access = await box(page, '.onboarding-access');
+ expect(access.width).toBeCloseTo(802.91, 1);
+ expect(access.x - collaboration.x).toBeCloseTo(150.55, 1);
+
+ const action = await box(page, '.onboarding-primary-action');
+ expect(round(action.height)).toBe(44);
+ expect(action.width).toBeGreaterThanOrEqual(144);
+
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath('welcome-1200x800-dark-en.png') });
+ expect(denied).toEqual([]);
+ });
+
+ // The design stacks the welcome with one rhythm: a 79 tall message block, then 24
+ // between every block (frame bi8Au, whose blocks sit at y=65/168/464/648 of its 756
+ // content box). The 1104 amendment makes the collaboration taller, so the blocks below
+ // it move down by that much and no other number changes.
+ test('welcome keeps the design vertical rhythm between its blocks', async ({ page }) => {
+ const denied = await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+
+ const heading = await box(page, '.onboarding-heading');
+ // The same type the design specifies: a 34/1.35 title, a 10 gap and a 14/1.57
+ // subtitle. The design reports 79 because it rounds each text box up on its own
+ // (46 + 10 + 23); the browser stacks the unrounded boxes to 77.9.
+ expect(heading.height).toBeCloseTo(77.89, 1);
+
+ const story = await box(page, '.onboarding-story');
+ const access = await box(page, '.onboarding-access');
+ const action = await box(page, '.onboarding-primary-action');
+ expect(story.y - (heading.y + heading.height)).toBeCloseTo(24, 0);
+ expect(access.y - (story.y + story.height)).toBeCloseTo(24, 0);
+ expect(action.y - (access.y + access.height)).toBeCloseTo(24, 0);
+ // The access block's own height is content, not cap: two 42 rows, an 8 gap, the
+ // caption and 17 of padding — the design's 160 at any width.
+ expect(round(access.height)).toBe(160);
+ expect(denied).toEqual([]);
+ });
+
+ /**
+ * The two steps are anchored differently because the design anchors them differently:
+ * JuwcG and KIxnF centre the welcome inside their frame, IWQi6 tops the setup out at
+ * its own 64.5 padding. So the welcome's y is a RESULT of the window height and the
+ * setup's is a position — and a test that pinned the welcome to 65 was asserting the
+ * one window height where those two happen to agree.
+ */
+ test('the welcome is centred by the window, and the setup is not', async ({ page }) => {
+ await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+
+ const centring = async () => {
+ const content = await box(page, '.onboarding-shell-content');
+ const welcome = await box(page, '.onboarding-welcome');
+ return {
+ above: welcome.y - content.y,
+ below: (content.y + content.height) - (welcome.y + welcome.height),
+ headingY: (await box(page, '.onboarding-heading')).y,
+ };
+ };
+
+ await page.setViewportSize({ width: 1200, height: 1200 });
+ const tall = await centring();
+ expect(Math.abs(tall.above - tall.below)).toBeLessThanOrEqual(1);
+ // Centred means it moved: a tall window puts the heading far below the setup's 65.
+ expect(tall.headingY).toBeGreaterThan(SETUP_TOP + 100);
+
+ // At the design's own content box the composition is taller than the window, so
+ // there is no slack to share and the same rule lands it on the content edge — where
+ // the frame draws it. The shell scrolls from there instead of clipping the top.
+ await page.setViewportSize(DESIGN_FRAME);
+ const short = await centring();
+ expect(short.above).toBeLessThanOrEqual(1);
+ expect(round(short.headingY)).toBe(SETUP_TOP);
+
+ await openSetup(page, 'en');
+ // The setup's top is the position itself, so it holds at both window heights.
+ expect(round((await box(page, '.onboarding-heading')).y)).toBe(SETUP_TOP);
+ await page.setViewportSize({ width: 1200, height: 1200 });
+ expect(round((await box(page, '.onboarding-heading')).y)).toBe(SETUP_TOP);
+ });
+
+ /**
+ * A short window used to buy about 30px by taking the step gaps from 24 to 16 and
+ * squeezing the access block — spending the design's own spacing at 1200x800, the
+ * reference's own frame size, where nothing was wrong. Whitespace IS the composition,
+ * so the shell scrolls instead and nothing about the type or the controls changes.
+ */
+ test('a short window scrolls rather than compressing the composition', async ({ page }) => {
+ await serveProduct(page);
+ await openOnboarding(page);
+ const metrics = () => page.evaluate(() => {
+ const read = (selector: string) => {
+ const node = document.querySelector(selector);
+ const style = node ? getComputedStyle(node) : null;
+ return style ? `${style.fontSize}/${style.lineHeight}` : 'missing';
+ };
+ const rect = (selector: string) => {
+ const found = document.querySelector(selector)?.getBoundingClientRect();
+ return found ? `${Math.round(found.width)}x${Math.round(found.height)}` : 'missing';
+ };
+ return {
+ type: [read('.onboarding-heading :is(h1, h2)'), read('.onboarding-heading p'), read('.onboarding-access-tile span')],
+ action: [rect('.onboarding-primary-action'), read('.onboarding-primary-action')],
+ access: rect('.onboarding-access'),
+ };
+ });
+ const tall = await metrics();
+
+ await page.setViewportSize(DESIGN_FRAME);
+ await freezeAt(page, PHASES['codex-working']);
+ expect(await metrics()).toEqual(tall);
+
+ const heading = await box(page, '.onboarding-heading');
+ const story = await box(page, '.onboarding-story');
+ const access = await box(page, '.onboarding-access');
+ const action = await box(page, '.onboarding-primary-action');
+ for (const gap of [story.y - (heading.y + heading.height), access.y - (story.y + story.height), action.y - (access.y + access.height)]) {
+ expect(gap).toBeCloseTo(24, 0);
+ }
+ // Scrolling is the accepted outcome, and it has to actually be reachable.
+ expect(await page.evaluate(() => document.documentElement.scrollHeight > window.innerHeight
+ || (document.querySelector('.onboarding-shell') as HTMLElement).scrollHeight > window.innerHeight)).toBe(true);
+ await page.locator('.onboarding-primary-action').scrollIntoViewIfNeeded();
+ await expect(page.locator('.onboarding-primary-action')).toBeInViewport();
+ });
+
+ test('assistant setup keeps the shared width, 88px rows and 12px spacing', async ({ page }, info) => {
+ const denied = await serveProduct(page);
+ await openOnboarding(page);
+ const welcomeTitle = await box(page, '.onboarding-heading :is(h1, h2)');
+ await openSetup(page, 'en');
+
+ const setupTitle = await box(page, '.onboarding-heading :is(h1, h2)');
+ // The title's box is shared between the steps; only its y differs, because only the
+ // welcome is centred. Asserting the height keeps the two from drifting apart.
+ expect(round(setupTitle.height)).toBe(round(welcomeTitle.height));
+
+ const assistants = await box(page, '.onboarding-assistants');
+ expect(round(assistants.width)).toBe(1104);
+ // The block keeps native sNs1V's 360 slot as a reserved minimum: small content growth
+ // — a detection error, an install chip — is absorbed by the slack already there
+ // instead of moving the button, and anything larger grows the block naturally.
+ expect(await page.locator('.onboarding-assistants').evaluate((node) => getComputedStyle(node).minHeight)).toBe('360px');
+ expect(assistants.height).toBeGreaterThanOrEqual(360);
+ await expect(page.locator('.onboarding-assistant')).toHaveCount(3);
+ for (let index = 0; index < 3; index += 1) {
+ const row = await box(page, '.onboarding-assistant', index);
+ // Width follows the shared cap; height stays the design's 88 because the row's
+ // content fits it, not because a fixed height forces it.
+ expect([round(row.width), round(row.height)]).toEqual([1104, 88]);
+ // Inside the row nothing was rescaled: a 44 well 20 from the edge, then identity
+ // 16 further in, exactly as frame i3vw9 lays every backend row out.
+ const logo = await box(page, '.onboarding-assistant-logo', index);
+ expect([round(logo.width), round(logo.height)]).toEqual([44, 44]);
+ expect(round(logo.x - row.x)).toBe(20);
+ expect(round(logo.y - row.y)).toBe(22);
+ const identity = await box(page, '.onboarding-assistant-identity', index);
+ expect(round(identity.x - row.x)).toBe(80);
+ }
+ // 12 between the section bar and the first row, and between rows (design pitch 100).
+ const header = await box(page, '.onboarding-assistants-header');
+ const [firstRow, secondRow] = await Promise.all([0, 1].map((index) => box(page, '.onboarding-assistant', index)));
+ expect(firstRow.y - (header.y + header.height)).toBeCloseTo(12, 0);
+ expect(round(secondRow.y - firstRow.y)).toBe(100);
+ // The setup heading keeps the welcome's 24 to the block below it.
+ const setupHeading = await box(page, '.onboarding-heading');
+ expect(header.y - (setupHeading.y + setupHeading.height)).toBeCloseTo(24, 0);
+ // And the same 24 below the slot, which puts the button 52 under the last row: the
+ // slot's own spare height plus that gap. Measuring both is what proves the 52 comes
+ // from the 360 slot rather than from a margin someone tuned to match it.
+ const footer = await box(page, '.onboarding-setup-footer');
+ const lastRow = await box(page, '.onboarding-assistant', 2);
+ const cta = await box(page, '.onboarding-primary-action');
+ expect(footer.y - (assistants.y + assistants.height)).toBeCloseTo(24, 0);
+ expect(cta.y - (lastRow.y + lastRow.height)).toBeCloseTo(52, 0);
+
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath('setup-1200x800-dark-en.png') });
+ expect(denied).toEqual([]);
+ });
+
+ // The live design sets one headline everywhere: 34/1.35/600 at -1.6 tracking (XKQOx,
+ // Igagh and hv9DA all agree), which is tighter than the browser default this shipped
+ // with. Both steps read it from the same rule, so both are checked.
+ test('both steps use the live design headline tracking', async ({ page }) => {
+ await serveProduct(page);
+ await openOnboarding(page);
+ const type = () => page.evaluate(() => {
+ const node = document.querySelector('.onboarding-heading :is(h1, h2)');
+ const style = node ? getComputedStyle(node) : null;
+ return style ? { size: style.fontSize, tracking: style.letterSpacing, weight: style.fontWeight } : null;
+ });
+ const expected = { size: '34px', tracking: '-1.6px', weight: '600' };
+ expect(await type()).toEqual(expected);
+ await openSetup(page, 'en');
+ expect(await type()).toEqual(expected);
+ });
+
+ test('every handoff pulse rides the wire that connects its two cards', async ({ page }, info) => {
+ const denied = await serveProduct(page);
+ await openOnboarding(page);
+ let clock = 0;
+ for (const [name, elapsed] of Object.entries(PHASES)) {
+ await freezeAt(page, elapsed - clock);
+ clock = elapsed;
+ const travelling = name.startsWith('handoff') || name === 'return-to-pm';
+ await expect(page.getByTestId('handoff-pulse')).toHaveCount(travelling ? 1 : 0);
+ await settleEffects(page);
+ await page.locator('.onboarding-collaboration').screenshot({ path: info.outputPath(`phase-${name}.png`) });
+ }
+ expect(denied).toEqual([]);
+ });
+});
+
+test.describe('capped fluid width', () => {
+ for (const viewport of VIEWPORTS) {
+ test(`fits ${size(viewport)} without horizontal overflow or clipping`, async ({ page }) => {
+ await page.setViewportSize(viewport);
+ const denied = await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+
+ expect(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth)).toBe(true);
+ const collaboration = await box(page, '.onboarding-collaboration');
+ // Capped fluid: never wider than the accepted cap, never wider than the viewport.
+ expect(collaboration.width).toBeLessThanOrEqual(1104);
+ expect(collaboration.width).toBeLessThanOrEqual(viewport.width);
+ const wires = await box(page, '.onboarding-wires');
+ // The stretched wire box always covers the cards, so no pulse can detach.
+ expect(round(wires.width)).toBe(round(collaboration.width));
+
+ // The primary action stays reachable: short viewports scroll rather than clip.
+ const action = page.locator('.onboarding-primary-action');
+ await action.scrollIntoViewIfNeeded();
+ await expect(action).toBeInViewport();
+ const clipped = await page.evaluate(() => {
+ const shell = document.querySelector('.onboarding-shell');
+ return shell ? getComputedStyle(shell).overflowY === 'hidden' : true;
+ });
+ expect(clipped).toBe(false);
+ expect(denied).toEqual([]);
+ });
+ }
+
+ /**
+ * The access block is drawn 640 wide on the diagram's own 880 box, so its edges land
+ * on the vertical legs of the return wire — the ports at x=120 and x=760. Checking
+ * that at the cap alone would pass on a block sized from a fixed number that happens
+ * to agree there, so it is checked at every width in between: only a width derived
+ * from the diagram's ACTUAL width can hold the relation at all of them.
+ */
+ for (const width of [1440, 1200, 1100, 1024, 900, 768]) {
+ test(`the access block spans the return wire legs at ${width}`, async ({ page }) => {
+ await page.setViewportSize({ width, height: 900 });
+ await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+
+ const access = await box(page, '.onboarding-access');
+ // PORTS index 5 is the x=120 leg and index 4 the x=760 one; `preserveAspectRatio`
+ // is none, so each maps to that share of the rendered width.
+ const left = await box(page, '.onboarding-port', 5);
+ const right = await box(page, '.onboarding-port', 4);
+ expect(access.x).toBeCloseTo(left.x + left.width / 2, 0);
+ expect(access.x + access.width).toBeCloseTo(right.x + right.width / 2, 0);
+ });
+ }
+
+ /**
+ * The one documented exception. Two columns of 640/880 of a phone would be about
+ * 200px of tiles inside a 360px screen, so below 600 the block takes the full content
+ * width and the tiles stay a readable target — deliberately leaving the wire relation
+ * rather than following it into an unusable size.
+ */
+ test('phones take the full content width instead, on purpose', async ({ page }) => {
+ await page.setViewportSize({ width: 390, height: 844 });
+ await serveProduct(page);
+ await openOnboarding(page);
+ const access = await box(page, '.onboarding-access');
+ const welcome = await box(page, '.onboarding-welcome');
+ expect(round(access.width)).toBe(round(welcome.width));
+ });
+
+ test('access tiles drop to two columns on phones and keep full labels', async ({ page }) => {
+ await page.setViewportSize({ width: 390, height: 844 });
+ await serveProduct(page);
+ await openOnboarding(page);
+ const tiles = page.locator('.onboarding-access-tile');
+ await expect(tiles).toHaveCount(6);
+ const rects = await tiles.evaluateAll((nodes) => nodes.map((node) => node.getBoundingClientRect().top));
+ expect(new Set(rects.map((top) => Math.round(top))).size).toBe(3);
+ const labels = await tiles.evaluateAll((nodes) => nodes.map((node) => node.scrollWidth <= node.clientWidth + 1));
+ expect(labels).toEqual([true, true, true, true, true, true]);
+ });
+});
+
+/**
+ * Narrow widths are where a card stops being a scaled copy of the design and becomes an
+ * adaptation, so the thing to check is that the adaptation is ONE arrangement rather
+ * than whichever one each label's length happens to produce. Every assertion here reads
+ * real bounding boxes: three status rows that start and end together, three identities
+ * that do, and no label clipped or truncated to make that true.
+ */
+test.describe('narrow identity alignment', () => {
+ for (const viewport of [{ width: 320, height: 568 }, { width: 390, height: 844 }, { width: 768, height: 1024 }]) {
+ for (const lang of ['en', 'zh'] as const) {
+ test(`${size(viewport)} ${lang} keeps the three cards on one grid`, async ({ page }, info) => {
+ await page.setViewportSize(viewport);
+ const denied = await serveProduct(page);
+ await openOnboarding(page, { lang });
+ await freezeAt(page, PHASES['codex-working']);
+
+ const statuses = await boxes(page, '.onboarding-story-status');
+ const identities = await boxes(page, '.onboarding-story-identity');
+ expect([statuses.length, identities.length]).toEqual([3, 3]);
+ // The header row and the separator above the footer are the two lines the eye
+ // reads across the three cards, so both have to be one line, not three.
+ expect(spread(statuses.map((one) => one.y))).toBeLessThanOrEqual(1);
+ expect(spread(statuses.map((one) => one.height))).toBeLessThanOrEqual(1);
+ expect(spread(identities.map((one) => one.y))).toBeLessThanOrEqual(1);
+ expect(spread(identities.map((one) => one.height))).toBeLessThanOrEqual(1);
+
+ // Alignment must not have been bought by cutting the labels: every name, role
+ // and caption is fully inside its own box, with no ellipsis doing the fitting.
+ const clipped = await page.locator(
+ '.onboarding-story-identity strong, .onboarding-story-identity > span:last-child, .onboarding-status-text',
+ ).evaluateAll((nodes) => nodes
+ .filter((node) => {
+ const style = getComputedStyle(node);
+ return node.scrollWidth > node.clientWidth + 1
+ || node.scrollHeight > node.clientHeight + 1
+ || style.textOverflow === 'ellipsis';
+ })
+ .map((node) => node.textContent?.trim() ?? ''));
+ expect(clipped).toEqual([]);
+ // …and the labels are still the product's own words at a readable size.
+ const names = await page.locator('.onboarding-story-identity strong').allInnerTexts();
+ expect(names.map((name) => name.replace(/\s+/g, ' ').trim())).toEqual(['Claude Code', 'Codex', 'OpenCode']);
+ const smallest = await page.locator('.onboarding-story-identity > span:last-child')
+ .evaluateAll((nodes) => Math.min(...nodes.map((node) => parseFloat(getComputedStyle(node).fontSize))));
+ expect(smallest).toBeGreaterThanOrEqual(10);
+
+ await settleEffects(page);
+ await page.locator('.onboarding-collaboration').screenshot({
+ path: info.outputPath(`identity-${size(viewport)}-${lang}.png`),
+ });
+ expect(denied).toEqual([]);
+ });
+ }
+ }
+});
+
+/**
+ * The approved design has no playback toolbar, so the story owns its own lifecycle:
+ * it starts with the screen, loops, and stops only for the two things the browser tells
+ * it about — a reduced-motion preference and a tab that is not being presented.
+ */
+test.describe('motion lifecycle', () => {
+ test.use({ viewport: { width: 1200, height: 800 } });
+
+ const PLAYBACK = /pause|play|resume|replay|restart|暂停|播放|重播|重新播放/i;
+
+ test('ships no playback control on either step', async ({ page }) => {
+ await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['tests-running']);
+
+ // Nothing inside the diagram is operable at all — not a button, not a control that
+ // merely looks like text, and not a reserved slot waiting for one.
+ await expect(page.locator('.onboarding-story button, .onboarding-story [role="button"], .onboarding-story input')).toHaveCount(0);
+ const named = async () => (await page.locator('button, [role="button"], input, a').evaluateAll((nodes) => nodes
+ .map((node) => `${node.getAttribute('aria-label') ?? ''} ${node.textContent ?? ''} ${node.getAttribute('title') ?? ''}`)))
+ .filter((label) => PLAYBACK.test(label));
+ expect(await named()).toEqual([]);
+ await openSetup(page, 'en');
+ expect(await named()).toEqual([]);
+ });
+
+ /**
+ * `page.clock` controls the timers the cards are read from; it does not control the
+ * document timeline the shimmer and the test ticks run on. So a suspension that only
+ * stopped the React clock would leave those playing on unseen and reappearing
+ * mid-sweep — which is why this asserts the RENDERED animation state, not the
+ * attribute that requests it.
+ */
+ test('a hidden tab freezes what is drawn, and resuming does not skip', async ({ page }) => {
+ await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+ const before = await renderedPhase(page);
+ expect(await cssEffects(page)).not.toEqual([]);
+
+ await setDocumentHidden(page, true);
+ await expect(page.locator('.onboarding-collaboration')).toHaveAttribute('data-motion', 'paused');
+ const stopped = await cssEffects(page);
+ expect(stopped.every((effect) => effect.state === 'paused')).toBe(true);
+
+ // Time passes while the tab is in the background, and nothing moves.
+ await page.clock.runFor(3000);
+ await page.waitForTimeout(250);
+ expect(await cssEffects(page)).toEqual(stopped);
+ expect(await renderedPhase(page)).toEqual(before);
+
+ await setDocumentHidden(page, false);
+ await expect(page.locator('.onboarding-collaboration')).toHaveAttribute('data-motion', 'running');
+ // Resuming continues the same sweep: the phase is where it was left, not where
+ // wall-clock time had carried it, and the CSS effects pick up their own timelines.
+ expect(await renderedPhase(page)).toEqual(before);
+ const resumed = await cssEffects(page);
+ expect(resumed.some((effect) => effect.state === 'running')).toBe(true);
+
+ // And it is genuinely running again, rather than merely unpaused.
+ await freezeAt(page, PHASES['pm-summary'] - PHASES['codex-working']);
+ expect(await renderedPhase(page)).not.toEqual(before);
+ });
+
+ /**
+ * The other half of the same lifecycle. A hidden tab is not the only way a story goes
+ * unwatched: at 390x300 the diagram and the button below it cannot share the screen, so
+ * reading the button puts the whole composition above the viewport while the document
+ * stays perfectly visible. Element visibility is what closes that, and `threshold: 0`
+ * is what keeps a partly scrolled composition alive instead of stuttering at the seam.
+ */
+ test('a story scrolled out of sight suspends, and partial visibility does not', async ({ page }, info) => {
+ const denied = await serveProduct(page);
+ await page.setViewportSize({ width: 390, height: 300 });
+ await openOnboarding(page);
+ await freezeAt(page, PHASES['codex-working']);
+ const diagram = page.locator('.onboarding-collaboration');
+ const rect = () => diagram.evaluate((node) => {
+ const found = node.getBoundingClientRect();
+ return { top: Math.round(found.top), bottom: Math.round(found.bottom) };
+ });
+ // Whichever element actually scrolls here, the page or the shell inside it.
+ const scrollBy = (delta: number) => page.evaluate((amount) => {
+ const shell = document.querySelector('.onboarding-shell') as HTMLElement | null;
+ const scroller = shell && shell.scrollHeight > shell.clientHeight ? shell : document.scrollingElement!;
+ scroller.scrollTop += amount;
+ }, delta);
+
+ await page.locator('.onboarding-primary-action').scrollIntoViewIfNeeded();
+ expect((await rect()).bottom).toBeLessThanOrEqual(0);
+ expect(await page.evaluate(() => document.hidden)).toBe(false);
+ await expect(diagram).toHaveAttribute('data-motion', 'paused');
+
+ const before = await renderedPhase(page);
+ const stopped = await cssEffects(page);
+ expect(stopped.every((effect) => effect.state === 'paused')).toBe(true);
+ await page.clock.runFor(3000);
+ await page.waitForTimeout(250);
+ expect(await renderedPhase(page)).toEqual(before);
+ expect(await cssEffects(page)).toEqual(stopped);
+ // The companion still for the design-frame crop: the CTA, reached by scrolling.
+ await page.screenshot({ path: info.outputPath('scrolled-cta-390x300.png') });
+
+ // Partly back: any intersecting pixel counts, so the story is live again at the seam.
+ await scrollBy(-100);
+ await page.waitForTimeout(150);
+ const seam = await rect();
+ expect(seam.top).toBeLessThan(0);
+ expect(seam.bottom).toBeGreaterThan(0);
+ await expect(diagram).toHaveAttribute('data-motion', 'running');
+
+ // And it resumed rather than restarted or skipped: the phase is the one it was
+ // holding, and it moves on from there once the clock runs again.
+ expect(await renderedPhase(page)).toEqual(before);
+ await freezeAt(page, PHASES['pm-summary'] - PHASES['codex-working']);
+ expect(await renderedPhase(page)).not.toEqual(before);
+ expect(denied).toEqual([]);
+ });
+
+ test('a reduced-motion preference draws the settled story and no pulse', async ({ page }, info) => {
+ await serveProduct(page);
+ await page.emulateMedia({ reducedMotion: 'reduce' });
+ await openOnboarding(page);
+ await expect(page.getByTestId('handoff-pulse')).toHaveCount(0);
+ expect(await cssEffects(page)).toEqual([]);
+ await page.screenshot({ path: info.outputPath('reduced-motion.png') });
+ });
+});
+
+/**
+ * The onboarding is the first screen a new install shows, so it is also the first place
+ * the theme has to behave: follow the system when nothing was chosen, and keep an
+ * explicit choice when the system disagrees with it.
+ */
+test.describe('theme', () => {
+ test.use({ viewport: { width: 1200, height: 800 } });
+
+ const themeState = (page: Page) => page.evaluate(() => ({
+ attribute: document.documentElement.getAttribute('data-theme'),
+ background: getComputedStyle(document.documentElement).getPropertyValue('--background').trim(),
+ }));
+
+ test('follows the system when no preference has been made', async ({ page }) => {
+ await serveProduct(page);
+ await page.emulateMedia({ colorScheme: 'dark' });
+ await openOnboarding(page, { theme: null });
+ const dark = await themeState(page);
+ // A fresh install starts in system mode, which sets no attribute at all: the
+ // stylesheet's own media query answers, and that is what lets the OS switch through
+ // without a reload.
+ expect(dark.attribute).toBeNull();
+
+ await page.emulateMedia({ colorScheme: 'light' });
+ const light = await themeState(page);
+ expect(light.attribute).toBeNull();
+ expect(light.background).not.toBe(dark.background);
+ });
+
+ test('keeps a stored preference when the system disagrees', async ({ page }) => {
+ await serveProduct(page);
+ await storeThemePreference(page, 'light');
+ await page.emulateMedia({ colorScheme: 'dark' });
+ await openOnboarding(page, { theme: null });
+ const chosen = await themeState(page);
+ expect(chosen.attribute).toBe('light');
+
+ // The OS moving underneath a made choice must not take it away, in either direction.
+ await page.emulateMedia({ colorScheme: 'light' });
+ expect(await themeState(page)).toEqual(chosen);
+ await page.emulateMedia({ colorScheme: 'dark' });
+ expect(await themeState(page)).toEqual(chosen);
+ await page.reload();
+ await page.locator('.onboarding-collaboration').waitFor();
+ expect((await themeState(page)).attribute).toBe('light');
+ });
+
+ /**
+ * The active card's halo is the one effect the reference specifies per theme: a
+ * spread-less 28px mint in dark, and light's own tighter 16/-4. It is asserted on the
+ * rendered `box-shadow` because the token behind it is substituted into its utilities
+ * at build time — reading the custom property would pass on a theme override that
+ * compiles to nothing.
+ */
+ for (const [theme, geometry] of [['dark', '0px 0px 28px 0px'], ['light', '0px 0px 16px -4px']] as const) {
+ test(`${theme} draws its own active-card halo, and idle cards none`, async ({ page }) => {
+ await serveProduct(page);
+ await openOnboarding(page, { theme });
+ await freezeAt(page, PHASES['codex-working']);
+ // The card fades its halo in over 650ms, so reading mid-transition measures the
+ // interpolation rather than the design's value. Settling first asks for the value
+ // the card actually arrives at.
+ await settleEffects(page);
+
+ const shadows = await page.locator('.onboarding-collaboration-card').evaluateAll((nodes) => nodes
+ .map((node) => ({ active: node.getAttribute('data-active'), shadow: getComputedStyle(node).boxShadow })));
+ const active = shadows.filter((card) => card.active === 'true');
+ expect(active).toHaveLength(1);
+ expect(active[0].shadow).toContain(geometry);
+ // The glow is what says which card is working, so it cannot also be on the others.
+ for (const card of shadows.filter((one) => one.active !== 'true')) expect(card.shadow).toBe('none');
+ });
+ }
+});
+
+test.describe('capture', () => {
+ for (const viewport of VIEWPORTS) {
+ for (const theme of ['dark', 'light'] as const) {
+ for (const lang of ['en', 'zh'] as const) {
+ // Settled stills: the clock is held at one named phase and every CSS effect is
+ // held past its end, so two runs — or two themes — produce the same drawing and
+ // it can be compared against a static frame. The phase is in the filename because
+ // a still that does not say which moment it is cannot be compared with anything.
+ test(`${size(viewport)} ${theme} ${lang}`, async ({ page }, info) => {
+ await page.setViewportSize(viewport);
+ await serveProduct(page);
+ await openOnboarding(page, { lang, theme });
+ await freezeAt(page, PHASES[CAPTURE_PHASE]);
+ expect((await renderedPhase(page)).states).toEqual(CAPTURE_STATES);
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath(`welcome-${size(viewport)}-${theme}-${lang}-${CAPTURE_PHASE}.png`), fullPage: true });
+ await openSetup(page, lang);
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath(`setup-${size(viewport)}-${theme}-${lang}.png`), fullPage: true });
+ });
+ }
+ }
+ }
+
+ // The design's own content box, for overlaying an exported frame at 1:1. This still is
+ // a VIEWPORT CROP, not the whole composition: at 756 the primary action sits below the
+ // fold, which is the accepted outcome rather than a layout the product should shrink to
+ // fit. The companion below shows it scrolled to, so the pair covers what one cannot.
+ test('design frame content box', async ({ page }, info) => {
+ await page.setViewportSize(DESIGN_FRAME);
+ await serveProduct(page);
+ await openOnboarding(page);
+ await freezeAt(page, PHASES[CAPTURE_PHASE]);
+ expect((await renderedPhase(page)).states).toEqual(CAPTURE_STATES);
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath(`welcome-design-frame-1200x756-${CAPTURE_PHASE}.png`) });
+ await page.locator('.onboarding-primary-action').scrollIntoViewIfNeeded();
+ await expect(page.locator('.onboarding-primary-action')).toBeInViewport();
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath(`welcome-design-frame-1200x756-cta-${CAPTURE_PHASE}.png`) });
+ await openSetup(page, 'en');
+ await settleEffects(page);
+ await page.screenshot({ path: info.outputPath('setup-design-frame-1200x756.png') });
+ });
+});
diff --git a/ui/e2e/onboarding-fidelity/loop.spec.ts b/ui/e2e/onboarding-fidelity/loop.spec.ts
new file mode 100644
index 000000000..ae453cce3
--- /dev/null
+++ b/ui/e2e/onboarding-fidelity/loop.spec.ts
@@ -0,0 +1,44 @@
+import { writeFile } from 'node:fs/promises';
+import { expect, test } from '@playwright/test';
+import { openOnboarding, renderedPhase, serveProduct, setDocumentHidden } from './support';
+
+/**
+ * The loop at the speed it was authored at, with no clock control anywhere: a video of
+ * one full 8.9s cycle plus a hide/show in the middle of it, and a sampled log of what
+ * the page was actually drawing at each step. This is the moving evidence — every
+ * capture in `geometry.spec.ts` is a settled still, and the two answer different
+ * questions. It lives in its own file because recording video is a per-file option.
+ */
+test.use({ viewport: { width: 1200, height: 800 }, video: 'on' });
+
+test('the story runs, suspends with the tab and resumes', async ({ page }, info) => {
+ const denied = await serveProduct(page);
+ await openOnboarding(page, { realTime: true });
+
+ const samples: { at: number; hidden: boolean; phase: Awaited<ReturnType<typeof renderedPhase>> }[] = [];
+ const started = Date.now();
+ for (let step = 0; step < 14; step += 1) {
+ if (step === 6) await setDocumentHidden(page, true);
+ if (step === 9) await setDocumentHidden(page, false);
+ const hidden = step >= 6 && step < 9;
+ samples.push({ at: Date.now() - started, hidden, phase: await renderedPhase(page) });
+ await page.waitForTimeout(800);
+ }
+
+ // The hidden samples are all the same frame: a background tab advances nothing.
+ const dark = samples.filter((sample) => sample.hidden);
+ for (const sample of dark) expect(sample.phase).toEqual(dark[0].phase);
+ // Over a full loop every card is seen working and every card is seen complete, so the
+ // recording really is of the whole cycle rather than one long phase.
+ const states = samples.map((sample) => sample.phase.states);
+ for (let card = 0; card < 3; card += 1) {
+ expect(states.some((state) => state[card] === 'working')).toBe(true);
+ expect(states.some((state) => state[card] === 'complete')).toBe(true);
+ }
+ // Written to the output directory rather than attached inline, so the log lands beside
+ // the video as a file a reviewer can open without a Playwright HTML report.
+ const log = info.outputPath('normal-speed-phases.json');
+ await writeFile(log, `${JSON.stringify(samples, null, 2)}\n`);
+ await info.attach('normal-speed-phases.json', { path: log, contentType: 'application/json' });
+ expect(denied).toEqual([]);
+});
diff --git a/ui/e2e/onboarding-fidelity/support.ts b/ui/e2e/onboarding-fidelity/support.ts
new file mode 100644
index 000000000..0d3c45cf9
--- /dev/null
+++ b/ui/e2e/onboarding-fidelity/support.ts
@@ -0,0 +1,201 @@
+import type { Page, Route } from '@playwright/test';
+
+export const ORIGIN = 'http://127.0.0.1:5212';
+
+/** Every phase of the authored 8.9s loop, addressed by the elapsed time it freezes at. */
+export const PHASES = {
+ 'pm-working': 600,
+ 'handoff-to-codex': 1875,
+ 'codex-working': 3000,
+ 'handoff-to-opencode': 4125,
+ 'tests-running': 5200,
+ 'return-to-pm': 6500,
+ 'pm-summary': 8000,
+} as const;
+
+export const VIEWPORTS = [
+ { width: 1200, height: 800 },
+ { width: 1440, height: 900 },
+ { width: 1024, height: 768 },
+ { width: 768, height: 1024 },
+ { width: 390, height: 844 },
+ { width: 320, height: 568 },
+] as const;
+
+export const size = ({ width, height }: { width: number; height: number }) => `${width}x${height}`;
+
+const CONFIG = {
+ platforms: { enabled: [] },
+ agents: {
+ claude: { enabled: true, cli_path: 'claude' },
+ codex: { enabled: true, cli_path: 'codex' },
+ opencode: { enabled: true, cli_path: 'opencode' },
+ },
+ agent: { default_cwd: '/fixture/work' },
+ show_duration: false,
+};
+
+const CATALOG = {
+ platforms: ['slack', 'discord', 'telegram', 'lark', 'wechat'].map((id) => ({ id, enabled: false })),
+};
+
+/**
+ * Answers the product's reads locally and refuses everything else. Any request that
+ * is not a same-origin GET — every write verb, and anything addressed off this
+ * fixture's origin — is aborted and recorded, so a capture can prove it never
+ * touched a running service or real user state.
+ */
+export async function serveProduct(page: Page) {
+ const denied: string[] = [];
+ await page.route('**/*', async (route: Route) => {
+ const request = route.request();
+ const method = request.method();
+ if (request.url().startsWith(ORIGIN) && (method === 'GET' || method === 'HEAD')) return route.fallback();
+ denied.push(`${method} ${request.url()}`);
+ return route.abort();
+ });
+ await page.route('**/api/config', (route) => route.fulfill({ json: CONFIG }));
+ await page.route('**/api/platforms', (route) => route.fulfill({ json: CATALOG }));
+ await page.route('**/api/settings**', (route) => route.fulfill({ json: { channels: {} } }));
+ await page.route('**/api/cli/detect**', (route) => {
+ const binary = new URL(route.request().url()).searchParams.get('binary') ?? '';
+ return route.fulfill({ json: { found: true, path: `/fixture/bin/${binary.split('/').pop()}` } });
+ });
+ // The setup step reads each assistant's runtime and OpenCode's permission flag. They
+ // are answered as an installed, permitted runtime so the screen renders the state the
+ // design describes rather than the error state a missing backend would produce.
+ await page.route('**/api/backend/*/runtime', (route) => {
+ const name = new URL(route.request().url()).pathname.split('/').at(-2);
+ return route.fulfill({
+ json: {
+ ok: true,
+ name,
+ enabled: true,
+ cli_path: name,
+ resolved_path: `/fixture/bin/${name}`,
+ installed: true,
+ current_version: '1.0.0',
+ latest_version: '1.0.0',
+ has_update: false,
+ supports_restart: true,
+ process_status: 'running',
+ },
+ });
+ });
+ await page.route('**/api/opencode/permission-status', (route) =>
+ route.fulfill({ json: { ok: true, permission_allowed: true } }),
+ );
+ return denied;
+}
+
+/**
+ * Loads the fixture with a frozen clock so a phase can be held still for comparison.
+ *
+ * `realTime` leaves the clock alone, which is what a recording of the loop needs: the
+ * story is meant to be watched at the speed it was authored at, and a frozen clock can
+ * only ever show it one still at a time.
+ */
+/** Any fixed instant; the story reads elapsed time, so only determinism matters. */
+const FIXED_TIME = new Date('2026-09-17T09:00:00Z');
+
+export async function openOnboarding(
+ page: Page,
+ options: { lang?: string; theme?: string | null; realTime?: boolean } = {},
+) {
+ if (!options.realTime) {
+ // `install` alone replaces the timers but leaves the clock ticking with real time,
+ // so the story still lands wherever wall-clock time carried it between two runs —
+ // which is how a dark and a light capture of "the same phase" end up different.
+ // `pauseAt` is what actually holds it: afterwards only `freezeAt` moves it.
+ await page.clock.install({ time: FIXED_TIME });
+ await page.clock.pauseAt(FIXED_TIME);
+ }
+ const query = new URLSearchParams({ lang: options.lang ?? 'en' });
+ // `theme: null` omits the parameter, which is the only way to watch the provider
+ // choose for itself — the query overrides the stored preference by design.
+ const theme = options.theme === undefined ? 'dark' : options.theme;
+ if (theme !== null) query.set('theme', theme);
+ await page.goto(`/e2e/onboarding-fidelity/fixture.html?${query}`);
+ await page.locator('.onboarding-collaboration').waitFor();
+}
+
+/** Seeds the Web UI's own theme key, the way a user who once picked one leaves it. */
+export function storeThemePreference(page: Page, mode: 'system' | 'light' | 'dark') {
+ return page.addInitScript((value) => {
+ window.localStorage.setItem('vibe-remote-theme', value);
+ }, mode);
+}
+
+/** Which card the story is drawing, and what it says — the phase, as the page shows it. */
+export function renderedPhase(page: Page) {
+ return page.evaluate(() => {
+ const cards = [...document.querySelectorAll('.onboarding-collaboration-card')];
+ return {
+ states: cards.map((card) => card.getAttribute('data-state') ?? ''),
+ captions: cards.map((card) => card.querySelector('.onboarding-status-text')?.textContent?.trim() ?? ''),
+ written: cards.map((card) => card.querySelectorAll('.onboarding-write-visible').length),
+ pulse: document.querySelectorAll('[data-testid="handoff-pulse"]').length,
+ };
+ });
+}
+
+/** Advances the frozen clock to an exact elapsed time inside the loop. */
+export async function freezeAt(page: Page, elapsed: number) {
+ await page.clock.runFor(elapsed);
+ await page.locator('.onboarding-collaboration-card[data-state]').first().waitFor();
+}
+
+/**
+ * Holds every CSS animation at one point of its OWN timeline. `page.clock` controls
+ * timers, which is what the story's clock is built from; it does not control the
+ * document timeline the shimmer and the test ticks run on. A screenshot taken after
+ * `freezeAt` alone therefore catches those wherever wall-clock time had carried them,
+ * and two runs of the same phase differ. Seeking past a `both`-filled animation's
+ * duration holds its end state, which is what a settled phase looks like — 1000ms
+ * clears the longest of them (750ms shimmer, 340ms ticks at a 480ms last delay).
+ */
+export async function settleEffects(page: Page, at = 1000) {
+ await page.evaluate((time) => {
+ for (const animation of document.getAnimations()) {
+ animation.currentTime = time;
+ animation.pause();
+ }
+ }, at);
+}
+
+/**
+ * What the CSS ANIMATIONS are actually doing, which is the state a DOM diff cannot see.
+ * Transitions are deliberately left out: `document.getAnimations()` returns those too,
+ * but a transition is finite and settles by itself, while an animation loops — so it is
+ * the animations that would otherwise play on unseen in a background tab, and only they
+ * that `animation-play-state` can hold.
+ */
+export function cssEffects(page: Page) {
+ return page.evaluate(() => document.getAnimations()
+ .filter((animation) => {
+ if (!('animationName' in animation)) return false;
+ // The onboarding's own motion, which is the whole of what its lifecycle owns.
+ const target = (animation.effect as KeyframeEffect | null)?.target ?? null;
+ return !!target?.closest('.onboarding-shell');
+ })
+ .map((animation) => ({
+ name: String((animation as unknown as { animationName: string }).animationName),
+ state: animation.playState,
+ at: Math.round(Number(animation.currentTime ?? 0)),
+ }))
+ .sort((left, right) => `${left.name}${left.at}`.localeCompare(`${right.name}${right.at}`)));
+}
+
+/** Simulates the tab going to the background, which no Playwright API does directly. */
+export async function setDocumentHidden(page: Page, hidden: boolean) {
+ await page.evaluate((value) => {
+ Object.defineProperty(document, 'hidden', { configurable: true, get: () => value });
+ Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => (value ? 'hidden' : 'visible') });
+ document.dispatchEvent(new Event('visibilitychange'));
+ }, hidden);
+}
+
+export async function openSetup(page: Page, lang: string) {
+ await page.getByRole('button', { name: lang === 'zh' ? '开始使用' : 'Get started' }).click();
+ await page.locator('.onboarding-assistants').waitFor();
+}
diff --git a/ui/e2e/onboarding-fidelity/tsconfig.json b/ui/e2e/onboarding-fidelity/tsconfig.json
new file mode 100644
index 000000000..a7b270eff
--- /dev/null
+++ b/ui/e2e/onboarding-fidelity/tsconfig.json
@@ -0,0 +1,6 @@
+{
+ "extends": "../../tsconfig.app.json",
+ "compilerOptions": { "types": ["vite/client", "node"] },
+ "include": ["*.ts", "*.tsx", "../../playwright.onboarding-fidelity.config.ts", "../../agentation.d.ts"],
+ "exclude": []
+}
diff --git a/ui/package.json b/ui/package.json
index d8a5cb2ca..43f65be41 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -25,6 +25,7 @@
"test:project-order": "tsc -p e2e/project-order/tsconfig.json --noEmit && playwright test --config playwright.project-order.config.ts",
"test:model-catalog": "tsc -p e2e/model-catalog/tsconfig.json --noEmit && playwright test --config playwright.model-catalog.config.ts",
"test:model-provider": "tsc -p e2e/model-provider/tsconfig.json --noEmit && playwright test --config playwright.model-provider.config.ts",
+ "test:onboarding-fidelity": "tsc -p e2e/onboarding-fidelity/tsconfig.json --noEmit && playwright test --config playwright.onboarding-fidelity.config.ts",
"validate:catalog": "node scripts/validate-scenario-catalog.mjs",
"validate:theme": "node scripts/validate-theme.mjs"
},
diff --git a/ui/playwright.onboarding-fidelity.config.ts b/ui/playwright.onboarding-fidelity.config.ts
new file mode 100644
index 000000000..493d98919
--- /dev/null
+++ b/ui/playwright.onboarding-fidelity.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Hermetic: the dev server is bound to loopback and points at a dead backend port,
+// and every request the page makes is answered or refused by the spec's own routes,
+// so nothing here reaches a running Avibe service or writes to user state.
+export default defineConfig({
+ testDir: './e2e/onboarding-fidelity',
+ outputDir: './e2e/.artifacts/onboarding-fidelity',
+ workers: 1,
+ retries: 0,
+ use: { baseURL: 'http://127.0.0.1:5212', trace: 'retain-on-failure' },
+ webServer: {
+ command: 'npm run dev -- --host 127.0.0.1 --port 5212 --strictPort',
+ env: { VIBE_UI_BACKEND: 'http://127.0.0.1:9' },
+ url: 'http://127.0.0.1:5212/e2e/onboarding-fidelity/fixture.html',
+ },
+ projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+});
diff --git a/ui/scripts/glowScale.test.mjs b/ui/scripts/glowScale.test.mjs
index d641f346f..c92f8e87a 100644
--- a/ui/scripts/glowScale.test.mjs
+++ b/ui/scripts/glowScale.test.mjs
@@ -68,7 +68,26 @@ const OFF_RULE = {
},
cta: {
why: 'owner-set: themed blur (2026-08-14) and 0.6 alpha, not from design.pen',
- holds: /^0 0 var\(--brand-glow-blur\) -4px rgba\(\d+, \d+, \d+, 0\.6\)$/,
+ holds: /^0 0 \d+px -4px rgba\(\d+, \d+, \d+, 0\.6\)$/,
+ },
+ // The approved onboarding reference draws its active card with no spread at all
+ // and at #5BFFA060, so the two fields the general rule fixes -- spread = -blur/4
+ // and alpha 0.44 -- are the two this role is excused from, and `holds` pins both
+ // at the reference's own numbers. Its blur is not excused: it is asserted from
+ // ROLE_BLUR like every other role's, because a role is still a name for a size.
+ //
+ // Two patterns, because the two frames drew this card separately: Light's own
+ // (waUhu) is 16/-4 at #10B98170, so the fields excused here are the ones that
+ // differ. An exception that named one theme would have left the other
+ // unasserted, which is this file's recurring failure shape -- so a themed
+ // exception states BOTH themes, and a theme it says nothing about fails rather
+ // than passing by default.
+ onboarding: {
+ why: 'the owner-approved active-card halo: spreadless #5BFFA060 in dark, and the light frame\'s own 16/-4 #10B98170',
+ holds: {
+ dark: /^0 0 \d+px 0px color-mix\(in srgb, var\(--[a-z]+\) 37\.6%, transparent\)$/,
+ light: /^0 0 \d+px -4px color-mix\(in srgb, var\(--[a-z]+\) 44%, transparent\)$/,
+ },
},
};
@@ -77,8 +96,77 @@ const OFF_RULE = {
// about which is 24 and which is 32, so swapping two rungs' blurs left every
// assertion here green and every converted call site one rung off its frame.
// A role is a name for a size; the mapping is the thing being asserted.
+// A role whose size is themed names one size per theme instead of one size. That is
+// not a softening: a single number still means "this blur in every theme", and a
+// themed role must state every theme or `blurOf` returns undefined and the assertion
+// fails. What it is NOT is an escape -- `onboarding` is pinned to 28 and 16, not
+// excused from having a blur, and `cta` is pinned to 16 and 20 where it used to be
+// excused entirely: "themed" was being read as "unasserted", so the owner's two
+// numbers were the only blurs in this file that nothing checked.
const ROLE_BLUR = {
dot: 8, wire: 4, xs: 12, sm: 16, md: 24, lg: 32, xl: 48,
+ cta: { dark: 16, light: 20 },
+ onboarding: { dark: 28, light: 16 },
+};
+
+const blurOf = (role, theme) => {
+ const blur = ROLE_BLUR[role];
+ return typeof blur === 'number' ? blur : blur?.[theme];
+};
+
+// Every rung is read under both palettes, not under the block it is written in.
+// That block is always `@theme`: the token layer is `@theme inline`, so Tailwind
+// substitutes each value into its utilities at build time and `validate:theme`
+// fails a later re-declaration of the same name as dead. Asking which theme a
+// DECLARATION belongs to therefore has one answer for every glow in the tree, and
+// the question worth asking is what the declaration draws once each palette has
+// supplied its own numbers.
+const THEMES = ['dark', 'light'];
+
+// Which is how a glow is themed at all, since a value cannot be. A hue follows the
+// palette on its own -- `color-mix(in srgb, var(--mint) …)` is whichever mint the
+// theme declares -- but a blur is a number, and a number that has to change per
+// theme has to be named and re-anchored where the palette is. `--brand-glow-blur`
+// is that shape and `--onboarding-glow-*` follows it.
+//
+// So a rung is resolved through the numbers its theme declares before anything is
+// asserted about it. Only the numbers: a colour name is left as written, because
+// "this token's colour is that accent" is an assertion below and resolving it away
+// would delete it. The whole-selector matching is the one `DARK_ACCENTS` explains
+// -- a substring test reads `:root:not([data-theme="dark"])`, the light block whose
+// entire job is to say it is not the dark one, as a dark declaration.
+const NUMBER = /^-?[\d.]+(px|%)?$/;
+
+const THEME_NUMBERS = (() => {
+ const numbers = { dark: new Map(), light: new Map() };
+ postcss.parse(CSS).walkRules((rule) => {
+ let light = rule.selectors.some((one) => one.trim() === '[data-theme="light"]');
+ for (let at = rule.parent; at && !light; at = at.parent) {
+ light = at.type === 'atrule' && at.name === 'media' && /prefers-color-scheme:\s*light/.test(at.params);
+ }
+ const dark = !light && rule.selectors.some((one) => [':root', '[data-theme="dark"]'].includes(one.trim()));
+ if (!light && !dark) return;
+
+ for (const node of rule.nodes ?? []) {
+ if (node.type !== 'decl' || !node.prop.startsWith('--') || !NUMBER.test(node.value.trim())) continue;
+ numbers[light ? 'light' : 'dark'].set(node.prop, node.value.trim());
+ }
+ });
+
+ // Light declares only what it changes, so it reads through dark for the rest --
+ // the cascade, which is what the browser does with these two blocks.
+ return { dark: numbers.dark, light: new Map([...numbers.dark, ...numbers.light]) };
+})();
+
+const resolveNumbers = (value, theme) => {
+ let resolved = value.replace(/\s+/g, ' ').trim();
+ for (let hop = 0; hop < 4; hop += 1) {
+ const next = resolved.replace(/var\((--[\w-]+)\)/g, (written, name) =>
+ THEME_NUMBERS[theme].get(name) ?? written);
+ if (next === resolved) break;
+ resolved = next;
+ }
+ return resolved;
};
const SPREAD_CAP = 12;
@@ -102,7 +190,15 @@ const rungs = SHEETS.flatMap(([, sheet]) => {
const found = [];
sheet.walkDecls((decl) => {
const match = RUNG_NAME.exec(decl.prop);
- if (match) found.push({ ...match.groups, token: decl.prop, value: decl.value });
+ // Every DECLARATION under every theme, not every name: reading one per name
+ // would leave whichever came second unchecked -- the same "collected, marked
+ // managed and discarded unread" hole the validator's own token layer had -- and
+ // reading one theme per declaration leaves the other palette's numbers
+ // unasserted, which is the same hole one level along.
+ if (!match) return;
+ for (const theme of THEMES) {
+ found.push({ ...match.groups, theme, token: decl.prop, value: resolveNumbers(decl.value, theme) });
+ }
});
return found;
});
@@ -184,12 +280,9 @@ describe('the accent glow scale', () => {
expect(MANAGED.filter((token) => !rungs.some((rung) => rung.token === token))).toEqual([]);
});
- // And the role a name parses into has to be one the scale defines. `role in
- // ROLE_BLUR` already decides which blur is asserted, but its else-branch --
- // "then it must carry a themed blur" -- describes `cta`, so an invented role
- // spelled with `var(--…)` would satisfy it. A role is a name for a size; a
- // name for no size is not a role.
- it.each(rungs)('$token names a role the scale defines', ({ role }) => {
+ // And the role a name parses into has to be one the scale defines. A role is a
+ // name for a size; a name for no size is not a role.
+ it.each(rungs)('$token in $theme names a role the scale defines', ({ role }) => {
expect(role in ROLE_BLUR || role in OFF_RULE, `${role} is on neither the blur scale nor the off-rule list`).toBe(true);
});
@@ -212,7 +305,7 @@ describe('the accent glow scale', () => {
// status dot was unasserted in every theme. A token named for an accent that
// draws a different one is the same defect as a blur off its frame, and it is
// the harder one to see by eye.
- it.each(rungs)('$token is its accent, as the dark theme declares it', ({ accent, value }) => {
+ it.each(rungs)('$token in $theme is its accent, as the dark theme declares it', ({ accent, value }) => {
const declared = DARK_ACCENTS.get(`--${accent}`);
expect(declared, `--${accent} is declared in no [data-theme="dark"] block`).toBeDefined();
expect([...declared], `--${accent} is declared more than once in dark`).toHaveLength(1);
@@ -233,12 +326,16 @@ describe('the accent glow scale', () => {
// A role is a name for a size, so the size is the assertion. Membership in a
// set of blurs cannot see two roles trading values.
- it.each(rungs)('$token has its role\'s blur', ({ role, value }) => {
- if (!(role in ROLE_BLUR)) {
- expect(value, `${role} has no fixed blur, so it must carry a themed one`).toMatch(/^0 0 var\(--[a-z-]+\) /);
- return;
- }
- expect(Number(value.match(/^0 0 (\d+)px/)?.[1])).toBe(ROLE_BLUR[role]);
+ //
+ // Every role, with no branch for a themed one. That branch read "then it must
+ // carry a themed blur", which described `cta` exactly -- and so accepted any
+ // number at all behind the variable, including a role invented that morning.
+ // Resolving a rung through its theme's own numbers is what removes the need for
+ // it: a themed blur is a number by the time it gets here.
+ it.each(rungs)('$token has its role\'s blur in $theme', ({ role, theme, value }) => {
+ const blur = blurOf(role, theme);
+ expect(blur, `${role} names no blur for the ${theme} theme it is declared in`).toBeDefined();
+ expect(Number(value.match(/^0 0 (\d+)px/)?.[1])).toBe(blur);
});
it.each(Object.entries(OFF_RULE))('states why %s is off the rule', (role, { why }) => {
@@ -248,8 +345,11 @@ describe('the accent glow scale', () => {
// Every accent's token of an off-rule role, so a role is covered across the
// palette rather than at whichever accent happens to be first.
- it.each(rungs.filter((rung) => rung.role in OFF_RULE))('$token holds its documented exception', ({ role, value }) => {
- expect(value.trim(), OFF_RULE[role].why).toMatch(OFF_RULE[role].holds);
+ it.each(rungs.filter((rung) => rung.role in OFF_RULE))('$token holds its documented exception in $theme', ({ role, theme, value }) => {
+ const { holds, why } = OFF_RULE[role];
+ const pattern = holds instanceof RegExp ? holds : holds[theme];
+ expect(pattern, `${role} states no exception for the ${theme} theme it is declared in`).toBeDefined();
+ expect(value.trim(), why).toMatch(pattern);
});
// Which comments count as design glow annotations, and what each one measures.
@@ -316,7 +416,8 @@ describe('the accent glow scale', () => {
// scale the test pins and not whatever index.css currently happens to say.
// Taking it from the file made the two agree by construction: a rung nudged
// to 40px became "spellable" in the same edit that broke its frame.
- const spellable = new Set(Object.values(ROLE_BLUR));
+ const spellable = new Set(Object.values(ROLE_BLUR)
+ .flatMap((blur) => (typeof blur === 'number' ? [blur] : Object.values(blur))));
expect([...annotated].filter((blur) => !spellable.has(blur)).sort((a, b) => a - b)).toEqual([]);
}, WHOLE_TREE_SCAN);
diff --git a/ui/src/components/Wizard.tsx b/ui/src/components/Wizard.tsx
index a5c1c6ea6..b5fbb4bee 100644
--- a/ui/src/components/Wizard.tsx
+++ b/ui/src/components/Wizard.tsx
@@ -22,7 +22,7 @@ import {
collectWizardEnabledPlatformDelta,
type WizardEnabledPlatformDelta,
} from '../lib/wizardConfigMutations';
-import { BrandLogo, WizardChrome } from './visual';
+import { WizardChrome } from './visual';
import { LanguageSwitcher } from './LanguageSwitcher';
export const Wizard: React.FC = () => {
@@ -245,8 +245,9 @@ export const Wizard: React.FC = () => {
if (isWelcome || stepId === 'agents') {
return (
<div className="onboarding-shell">
+ {/* The 2026-09-17 design drops the brand mark from the guidance screens
+ ("这些引导页的logo都去掉"); the language switcher keeps the bar. */}
<header>
- <div className="flex items-center gap-2.5"><BrandLogo size={32} /><span className="text-sm font-semibold">Avibe</span></div>
<LanguageSwitcher />
</header>
<main className="onboarding-shell-content">
diff --git a/ui/src/components/onboarding/AccessTiles.tsx b/ui/src/components/onboarding/AccessTiles.tsx
index bc791bcec..b37b7a317 100644
--- a/ui/src/components/onboarding/AccessTiles.tsx
+++ b/ui/src/components/onboarding/AccessTiles.tsx
@@ -1,17 +1,20 @@
import { useEffect, useState } from 'react';
-import { useReducedMotion } from 'framer-motion';
import { useTranslation } from 'react-i18next';
import { PlatformIcon } from '../visual';
+import { useOnboardingMotion } from './motion';
const PLATFORMS = ['avibe', 'slack', 'discord', 'telegram', 'lark', 'wechat'];
-export function AccessTiles({ paused }: { paused: boolean }) {
+export function AccessTiles() {
const { t } = useTranslation();
- const reducedMotion = useReducedMotion() === true;
+ const { ref, running } = useOnboardingMotion();
const [pointerInside, setPointerInside] = useState(false);
const [focusInside, setFocusInside] = useState(false);
const [emphasis, setEmphasis] = useState<number | null>(null);
- const automatic = !paused && !reducedMotion && !pointerInside && !focusInside;
+ // Same lifecycle as the story: a hidden tab, a reduced-motion preference, or these
+ // tiles being scrolled out of sight stops the rotation; pointer and keyboard
+ // interaction still yield the emphasis to the user.
+ const automatic = running && !pointerInside && !focusInside;
useEffect(() => {
if (!automatic) return;
const timer = window.setInterval(() => {
@@ -22,7 +25,7 @@ export function AccessTiles({ paused }: { paused: boolean }) {
}, [automatic]);
return (
- <section className="onboarding-access" aria-label={t('onboarding.access.label')}>
+ <section ref={ref} className="onboarding-access" aria-label={t('onboarding.access.label')}>
<p>{t('onboarding.access.description')}</p>
<ul className="onboarding-access-grid" onPointerEnter={() => setPointerInside(true)} onPointerLeave={() => setPointerInside(false)}
onFocus={() => setFocusInside(true)} onBlur={(event) => { if (!event.currentTarget.contains(event.relatedTarget)) setFocusInside(false); }}>
diff --git a/ui/src/components/onboarding/CollaborationStory.tsx b/ui/src/components/onboarding/CollaborationStory.tsx
index f81e99693..e297170d9 100644
--- a/ui/src/components/onboarding/CollaborationStory.tsx
+++ b/ui/src/components/onboarding/CollaborationStory.tsx
@@ -1,81 +1,178 @@
-import { useEffect, useState } from 'react';
-import { CodeXml, FileText, ListChecks, Pause, Play, RotateCcw } from 'lucide-react';
+import { useEffect, useId, useState } from 'react';
+import { Check, CodeXml, FileText, ListChecks } from 'lucide-react';
import { useTranslation } from 'react-i18next';
-import { useReducedMotion } from 'framer-motion';
import { BackendIcon } from '../visual';
-import { Button } from '../ui/button';
import { Card } from '../ui/card';
-import { ASSISTANT_ORDER, collaborationFrame } from './collaborationTimeline';
+import { ASSISTANT_ORDER, WORK_LINES, collaborationFrame } from './collaborationTimeline';
+import { useOnboardingMotion } from './motion';
-export function CollaborationStory({ paused, onPausedChange }: {
- paused: boolean;
- onPausedChange: (paused: boolean) => void;
-}) {
+/** Wire geometry in the 880x272 collaboration box: two handoffs and the rounded return loop. */
+const WIRES = [
+ 'M240 118H320',
+ 'M560 118H640',
+ 'M760 228V246Q760 262 744 262H136Q120 262 120 246V228',
+];
+const PORTS: [number, number][] = [[240, 118], [320, 118], [560, 118], [640, 118], [760, 228], [120, 228]];
+const ICONS = [FileText, CodeXml, ListChecks];
+// Every skeleton line as its share of the block it is measured in, so the three cards
+// draw the widths design_desktop.pen draws at any scale. The card's content box is 198
+// wide; a document line is a share of that, a test line too (the checkbox and its gap
+// are laid beside it, not out of it), and a code line is a share of the bar column that
+// starts after the line number — which is why those two sets have different bases.
+const DOCUMENT_BARS = [55.1, 94.9, 79.3, 36.9, 89.4, 65.7];
+const CODE_INDENT = [0, 10, 20, 20, 10, 0];
+const CODE_BARS: [number, number][] = [[24.3, 30.4], [18.1, 43.3], [29.2, 23], [21.7, 33.5], [31.6, 14.6], [14.4, 0]];
+const TEST_BARS = [73.2, 61.6, 82.3, 54.5];
+
+function Bar({ width, tone, revealed }: { width: number; tone?: string; revealed?: boolean }) {
+ const reveal = revealed === undefined ? ''
+ : `onboarding-write-line ${revealed ? 'onboarding-write-visible' : ''}`;
+ return <span className={`onboarding-bar ${tone ?? ''} ${reveal}`} style={{ width: `${width}%` }} />;
+}
+
+/**
+ * One ring stays mounted from the first frame of work through completion: it draws itself as the
+ * work progresses, closes, and the check then grows from its hinge toward both ends.
+ */
+function WorkStatus({ active, done, progress }: { active: boolean; done: boolean; progress: number }) {
+ return (
+ <span className="onboarding-status-glyph" aria-hidden="true">
+ {active || done ? (
+ <svg className="onboarding-status-mark" viewBox="0 0 20 20" fill="none">
+ <circle className="onboarding-status-ring" cx="10" cy="10" r="8" pathLength="1"
+ transform="rotate(-90 10 10)" style={{ strokeDashoffset: done ? 0 : 1 - progress }} />
+ {done && (
+ <g className="onboarding-status-check">
+ <path d="M8.5 12.5 5.5 9.5" />
+ <path d="M8.5 12.5 14.5 6.5" />
+ </g>
+ )}
+ </svg>
+ ) : <span className="onboarding-status-dot" />}
+ </span>
+ );
+}
+
+function Skeleton({ backend, done, written }: { backend: string; done: boolean; written: number }) {
+ if (backend === 'claude') {
+ return (
+ <div className="onboarding-skeleton onboarding-skeleton-document">
+ <Bar width={DOCUMENT_BARS[0]} tone="onboarding-bar-heading" revealed={written > 0} />
+ <Bar width={DOCUMENT_BARS[1]} revealed={written > 1} />
+ <Bar width={DOCUMENT_BARS[2]} revealed={written > 2} />
+ <div className="onboarding-skeleton-paragraph">
+ <Bar width={DOCUMENT_BARS[3]} tone="onboarding-bar-subheading" revealed={written > 3} />
+ <Bar width={DOCUMENT_BARS[4]} revealed={written > 4} />
+ <Bar width={DOCUMENT_BARS[5]} revealed={written > 5} />
+ </div>
+ </div>
+ );
+ }
+ if (backend === 'codex') {
+ return (
+ <div className="onboarding-skeleton onboarding-skeleton-code">
+ {CODE_BARS.map(([first, second], line) => (
+ <div key={line} className={`onboarding-code-row onboarding-write-line ${written > line ? 'onboarding-write-visible' : ''}`}>
+ <span className="onboarding-code-number">{line + 1}</span>
+ {/* The indent is geometry, not type, so it scales with the diagram. */}
+ <div className="onboarding-code-bars" style={{ paddingLeft: `calc(${CODE_INDENT[line]} * var(--ob-u))` }}>
+ <Bar width={first} tone={line % 2 ? 'onboarding-bar-violet' : 'onboarding-bar-cyan'} />
+ <Bar width={second} />
+ </div>
+ </div>
+ ))}
+ </div>
+ );
+ }
+ return (
+ <div className={`onboarding-skeleton onboarding-skeleton-tests ${done ? 'onboarding-tests-done' : ''}`}>
+ {TEST_BARS.map((width, line) => (
+ <div key={line} className="onboarding-test-row" style={{ '--test-index': line } as React.CSSProperties}>
+ <span className="onboarding-test-check"><Check size={10} strokeWidth={3} /></span>
+ <Bar width={width} />
+ </div>
+ ))}
+ </div>
+ );
+}
+
+/** The wires are stretched to the card grid, so every coordinate stays proportional. */
+function Circuit({ handoff }: { handoff: { wire: number; progress: number } | null }) {
+ const glowId = useId();
+ const pulse = handoff && {
+ strokeDashoffset: 16 - 100 * handoff.progress,
+ opacity: Math.max(0, Math.min(1, handoff.progress / 0.08, (1 - handoff.progress) / 0.06)),
+ };
+ return (
+ <svg className="onboarding-wires" viewBox="0 0 880 272" fill="none" preserveAspectRatio="none" aria-hidden="true">
+ <defs>
+ <filter id={glowId} x="-100%" y="-500%" width="300%" height="1100%"><feGaussianBlur stdDeviation="3" /></filter>
+ </defs>
+ {WIRES.map((d, index) => (
+ <g key={d}>
+ <path className="onboarding-wire" d={d} />
+ {handoff?.wire === index && (
+ <g data-testid="handoff-pulse">
+ <path className="onboarding-pulse-halo" d={d} pathLength={100} style={{ ...pulse, filter: `url(#${glowId})` }} />
+ <path className="onboarding-pulse-core" d={d} pathLength={100} style={pulse ?? undefined} />
+ </g>
+ )}
+ </g>
+ ))}
+ {PORTS.map(([x, y]) => <circle key={`${x}-${y}`} className="onboarding-port" cx={x} cy={y} r={3} />)}
+ </svg>
+ );
+}
+
+/** The design has no playback controls, so the loop starts with the screen and owns itself. */
+export function CollaborationStory() {
const { t } = useTranslation();
- const reducedMotion = useReducedMotion() === true;
+ const { ref, reducedMotion, running } = useOnboardingMotion();
const [elapsed, setElapsed] = useState(0);
useEffect(() => {
- if (paused || reducedMotion) return;
+ if (!running) return;
let previous = performance.now();
const timer = window.setInterval(() => {
const now = performance.now();
const delta = now - previous;
previous = now;
setElapsed((value) => value + delta);
- }, 50);
+ }, 16);
return () => window.clearInterval(timer);
- }, [paused, reducedMotion]);
+ }, [running]);
const frame = collaborationFrame(elapsed, reducedMotion);
- const paths = ['M240 112 H320', 'M560 112 H640', 'M760 228 V260 H120 V228'];
- const icons = [FileText, CodeXml, ListChecks];
return (
<section className="onboarding-story" aria-label={t('onboarding.story.label')}>
<p className="sr-only">{t('onboarding.story.description')}</p>
- <div className="onboarding-collaboration" data-reduced-motion={reducedMotion}>
- <svg className="onboarding-wires" viewBox="0 0 880 272" aria-hidden="true">
- {paths.map((path) => <path key={path} d={path} fill="none" stroke="var(--border-strong)" />)}
- {frame.handoff && !reducedMotion && (
- <path data-testid="handoff-pulse" d={paths[frame.handoff.path]} fill="none"
- stroke="var(--mint)" strokeWidth="2" pathLength="1" strokeDasharray="0.06 1"
- strokeDashoffset={-frame.handoff.progress * 0.94} />
- )}
- </svg>
+ {/* `data-motion` hands the same running state to the stylesheet: when the diagram
+ is not being presented — the tab is hidden, or it has been scrolled out of
+ sight — it holds every CSS animation inside at its current frame instead of
+ letting it play on unseen against a stopped clock. The ref is what makes the
+ second of those readable: it is this element's own visibility that decides. */}
+ <div ref={ref} className="onboarding-collaboration" data-reduced-motion={reducedMotion}
+ data-motion={running ? 'running' : 'paused'}>
+ <Circuit handoff={frame.handoff} />
<div className="onboarding-collaboration-cards">
{ASSISTANT_ORDER.map((backend, index) => {
- const progress = frame.progress[index];
- const state = progress >= 1 ? 'complete' : progress > 0 ? 'working' : 'waiting';
- const Icon = icons[index];
- const phase = index === 0 && frame.summary ? 'summary' : state;
+ const done = frame.done[index];
+ const active = frame.active === index;
+ const state = done ? 'complete' : active ? 'working' : 'waiting';
+ const summary = index === 0 && frame.summary;
+ const caption = summary ? t('onboarding.story.claude.summary')
+ : t(`onboarding.story.${backend}.${done ? 'complete' : 'working'}`);
+ const Icon = ICONS[index];
return (
- <Card key={backend} className="onboarding-collaboration-card" data-active={frame.active === index}
+ <Card key={backend} className="onboarding-collaboration-card" data-active={active}
data-state={state} aria-label={t(`onboarding.story.${backend}.name`)}>
<div className="onboarding-story-status" aria-hidden="true">
- <Icon size={13} />
- <span key={phase} className={paused ? '' : 'onboarding-status-copy'}>
- {phase === 'summary' ? t('onboarding.story.claude.summary') : t(`onboarding.story.${backend}.${state}`)}
+ <Icon size={13} strokeWidth={1.7} className="onboarding-status-icon" />
+ <span key={caption} className="onboarding-status-text onboarding-status-enter">
+ {caption}
</span>
- <svg viewBox="0 0 14 14" className="onboarding-status-glyph">
- <circle cx="7" cy="7" r="2.5" fill="currentColor" opacity={state === 'waiting' ? 0.5 : 0} />
- <circle cx="7" cy="7" r="5.5" fill="none" stroke="var(--mint)" strokeWidth="1.2"
- pathLength="1" strokeDasharray="1" strokeDashoffset={1 - Math.min(1, progress * 1500 / 850)}
- transform="rotate(-90 7 7)" />
- <path d="m4.4 7 1.7 1.8 3.7-3.6" fill="none" stroke="var(--mint)" strokeWidth="1.3"
- pathLength="1" strokeDasharray="1" strokeDashoffset={1 - Math.max(0, Math.min(1, (progress * 1500 - 850) / 300))} />
- </svg>
- </div>
- <div className={`onboarding-skeleton onboarding-skeleton-${backend}`} aria-hidden="true">
- {Array.from({ length: index === 2 ? 4 : 6 }, (_, line) => {
- const revealed = progress >= (line + 1) / (index === 2 ? 4 : 6);
- return (
- <div key={line} className="onboarding-skeleton-row" style={{ opacity: revealed ? 1 : 0.2 }}>
- {index === 1 && <span className="onboarding-code-number">{line + 1}</span>}
- {index === 2 && <span className="onboarding-test-check">{revealed ? '✓' : ''}</span>}
- <span className="onboarding-skeleton-line" style={{ width: `${[90, 75, 84, 62, 80, 68][line]}%` }} />
- </div>
- );
- })}
+ <WorkStatus active={active} done={done} progress={frame.progress[index]} />
</div>
+ <Skeleton backend={backend} done={done} written={reducedMotion ? WORK_LINES : frame.written[index]} />
<div className="onboarding-story-identity">
<BackendIcon backend={backend} size={28} variant="glyph" aria-hidden="true" />
<strong>{t(`onboarding.story.${backend}.name`)}</strong>
@@ -85,18 +182,10 @@ export function CollaborationStory({ paused, onPausedChange }: {
);
})}
</div>
- <p className="onboarding-story-caption">{t('onboarding.story.caption')}</p>
+ <p className="onboarding-story-caption" data-returning={frame.returning}>
+ {t(frame.returning ? 'onboarding.story.returnCaption' : 'onboarding.story.caption')}
+ </p>
</div>
- {!reducedMotion && (
- <div className="onboarding-motion-controls">
- <Button variant="ghost" size="icon" className="size-7" onClick={() => onPausedChange(!paused)}
- aria-label={t(paused ? 'onboarding.story.play' : 'onboarding.story.pause')}>
- {paused ? <Play size={12} /> : <Pause size={12} />}
- </Button>
- <Button variant="ghost" size="icon" className="size-7" onClick={() => { setElapsed(0); onPausedChange(false); }}
- aria-label={t('onboarding.story.replay')}><RotateCcw size={12} /></Button>
- </div>
- )}
</section>
);
}
diff --git a/ui/src/components/onboarding/Welcome.test.tsx b/ui/src/components/onboarding/Welcome.test.tsx
index 62c473e2d..78e83a616 100644
--- a/ui/src/components/onboarding/Welcome.test.tsx
+++ b/ui/src/components/onboarding/Welcome.test.tsx
@@ -15,8 +15,44 @@ vi.mock('../../context/ApiContext', () => ({ useApi: () => mocks.api }));
const i18n = createInstance();
await i18n.init({ lng: 'en', resources: { en: { translation: en }, zh: { translation: zh } }, interpolation: { escapeValue: false } });
const wrap = (element: React.ReactNode) => <I18nextProvider i18n={i18n}>{element}</I18nextProvider>;
+
+/** The tab going to the background, which jsdom exposes no other way. */
+const setHidden = (hidden: boolean) => act(() => {
+ Object.defineProperty(document, 'hidden', { configurable: true, get: () => hidden });
+ Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => (hidden ? 'hidden' : 'visible') });
+ document.dispatchEvent(new Event('visibilitychange'));
+});
+
+/**
+ * The composition scrolling out of sight, which jsdom exposes no other way either: it
+ * ships no IntersectionObserver at all. The stub keeps the real contract — observe an
+ * element, report whether it intersects — and hands back a switch the test can flip.
+ */
+function stubIntersectionObserver() {
+ const report: ((onScreen: boolean) => void)[] = [];
+ class Stub {
+ constructor(callback: IntersectionObserverCallback) {
+ report.push((onScreen) => callback(
+ [{ isIntersecting: onScreen } as IntersectionObserverEntry],
+ this as unknown as IntersectionObserver,
+ ));
+ }
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+ }
+ vi.stubGlobal('IntersectionObserver', Stub);
+ return (onScreen: boolean) => act(() => { for (const notify of report) notify(onScreen); });
+}
+
beforeEach(() => { mocks.reduced = false; vi.clearAllMocks(); void i18n.changeLanguage('en'); });
-afterEach(() => { cleanup(); vi.useRealTimers(); });
+afterEach(() => {
+ cleanup();
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ delete (document as Partial<Document>).hidden;
+ delete (document as Partial<Document>).visibilityState;
+});
describe('Welcome', () => {
it('checks saved paths before advancing without persisting configuration', async () => {
@@ -47,40 +83,86 @@ describe('Welcome', () => {
});
});
-describe('collaboration playback and access interaction', () => {
- it('advances the pulse and freezes the entire state on pause', () => {
+describe('collaboration lifecycle and access interaction', () => {
+ it('starts on its own and offers no playback control', () => {
vi.useFakeTimers();
- const { container, rerender } = render(wrap(<CollaborationStory paused={false} onPausedChange={vi.fn()} />));
+ const { container } = render(wrap(<CollaborationStory />));
act(() => vi.advanceTimersByTime(1800));
expect(screen.getByTestId('handoff-pulse')).toBeTruthy();
expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(1);
- rerender(wrap(<CollaborationStory paused onPausedChange={vi.fn()} />));
- const before = container.innerHTML;
+ // The approved design has no playback toolbar, so the story ships no control at all —
+ // not a renamed one, not a hidden one, not a keyboard-only one.
+ expect(container.querySelectorAll('button, [role="button"], input')).toHaveLength(0);
+ });
+ it('holds the story still while the tab is hidden and resumes in the same phase', () => {
+ vi.useFakeTimers();
+ const { container } = render(wrap(<CollaborationStory />));
+ const diagram = () => container.querySelector('.onboarding-collaboration') as HTMLElement;
+ act(() => vi.advanceTimersByTime(5000));
+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);
+ expect(diagram().dataset.motion).toBe('running');
+
+ setHidden(true);
+ // `data-motion` is what holds the rendered CSS animations; the cleared timer is what
+ // holds the React frame. Both have to stop, or the diagram plays on against a clock
+ // nobody is watching and jumps when the tab comes back.
+ expect(diagram().dataset.motion).toBe('paused');
+ expect(vi.getTimerCount()).toBe(0);
+ const frozen = container.innerHTML;
act(() => vi.advanceTimersByTime(3000));
- expect(container.innerHTML).toBe(before);
+ expect(container.innerHTML).toBe(frozen);
+
+ setHidden(false);
+ expect(diagram().dataset.motion).toBe('running');
+ expect(vi.getTimerCount()).toBe(1);
+ // Continuity, not restart: the 3000ms spent hidden would have carried the third card
+ // past its completion, and a restart would have emptied all three.
+ act(() => vi.advanceTimersByTime(100));
+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);
+ act(() => vi.advanceTimersByTime(400));
+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(3);
});
- it('replays every card and pulse from the same beginning', () => {
+ it('holds the story still while it is scrolled out of sight, with the tab still visible', () => {
vi.useFakeTimers();
- const resume = vi.fn();
- const { container } = render(wrap(<CollaborationStory paused={false} onPausedChange={resume} />));
+ const scroll = stubIntersectionObserver();
+ const { container } = render(wrap(<CollaborationStory />));
+ const diagram = () => container.querySelector('.onboarding-collaboration') as HTMLElement;
act(() => vi.advanceTimersByTime(5000));
expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);
- fireEvent.click(screen.getByRole('button', { name: 'Replay animation' }));
- expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(0);
- expect(screen.queryByTestId('handoff-pulse')).toBeNull();
- expect(resume).toHaveBeenCalledWith(false);
+ expect(diagram().dataset.motion).toBe('running');
+
+ // A hidden tab is only half the lifecycle. Here the document is perfectly visible
+ // and it is the diagram that has left the screen — on a short window it can sit
+ // entirely above the viewport while the user reads the button below it.
+ scroll(false);
+ expect(document.hidden).toBeFalsy();
+ expect(diagram().dataset.motion).toBe('paused');
+ expect(vi.getTimerCount()).toBe(0);
+ const frozen = container.innerHTML;
+ act(() => vi.advanceTimersByTime(3000));
+ expect(container.innerHTML).toBe(frozen);
+
+ scroll(true);
+ expect(diagram().dataset.motion).toBe('running');
+ expect(vi.getTimerCount()).toBe(1);
+ // Continuity, not restart, exactly as for the hidden tab above.
+ act(() => vi.advanceTimersByTime(100));
+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(2);
+ act(() => vi.advanceTimersByTime(400));
+ expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(3);
});
it('shows completed work and stops all timers for reduced motion', () => {
vi.useFakeTimers(); mocks.reduced = true;
const { container } = render(wrap(<Welcome onNext={vi.fn()} />));
expect(container.querySelectorAll('[data-state="complete"]')).toHaveLength(3);
expect(screen.queryByTestId('handoff-pulse')).toBeNull();
- expect(screen.queryByRole('button', { name: 'Pause animation' })).toBeNull();
+ // Get started is the only button on the screen.
+ expect(screen.getAllByRole('button').map((node) => node.textContent?.trim())).toEqual(['Get started']);
expect(vi.getTimerCount()).toBe(0);
});
it('pauses idle emphasis throughout pointer and keyboard interaction', () => {
vi.useFakeTimers();
- const { container } = render(wrap(<AccessTiles paused={false} />));
+ const { container } = render(wrap(<AccessTiles />));
act(() => vi.advanceTimersByTime(2000));
expect(container.querySelectorAll('[data-emphasis="true"]')).toHaveLength(1);
fireEvent.pointerEnter(screen.getByRole('list'));
@@ -92,4 +174,28 @@ describe('collaboration playback and access interaction', () => {
fireEvent.blur(screen.getAllByRole('listitem')[0], { relatedTarget: null });
expect(vi.getTimerCount()).toBe(1);
});
+ it('stops the access rotation with the tab and keeps it stopped for reduced motion', () => {
+ vi.useFakeTimers();
+ const { container } = render(wrap(<AccessTiles />));
+ act(() => vi.advanceTimersByTime(2000));
+ expect(container.querySelectorAll('[data-emphasis="true"]')).toHaveLength(1);
+ setHidden(true);
+ expect(vi.getTimerCount()).toBe(0);
+ expect(container.querySelectorAll('[data-emphasis="true"]')).toHaveLength(0);
+ setHidden(false);
+ expect(vi.getTimerCount()).toBe(1);
+ });
+ it('stops the access rotation when the tiles themselves scroll out of sight', () => {
+ vi.useFakeTimers();
+ const scroll = stubIntersectionObserver();
+ const { container } = render(wrap(<AccessTiles />));
+ act(() => vi.advanceTimersByTime(2000));
+ expect(vi.getTimerCount()).toBe(1);
+ scroll(false);
+ expect(vi.getTimerCount()).toBe(0);
+ scroll(true);
+ expect(vi.getTimerCount()).toBe(1);
+ // The rotation is what suspends; the six tiles it rotates through are always there.
+ expect(container.querySelectorAll('.onboarding-access-tile')).toHaveLength(6);
+ });
});
diff --git a/ui/src/components/onboarding/collaborationTimeline.test.ts b/ui/src/components/onboarding/collaborationTimeline.test.ts
index b53b161af..c73fb5c42 100644
--- a/ui/src/components/onboarding/collaborationTimeline.test.ts
+++ b/ui/src/components/onboarding/collaborationTimeline.test.ts
@@ -1,25 +1,49 @@
import { describe, expect, it } from 'vitest';
-import { collaborationFrame } from './collaborationTimeline';
+import { COLLABORATION_DURATION, WORK_LINES, collaborationFrame } from './collaborationTimeline';
describe('one collaboration clock', () => {
it('keeps the source active until each pulse arrives', () => {
- for (const [start, end, source, destination, path] of [[1500, 2250, 0, 1, 0], [3750, 4500, 1, 2, 1], [6000, 7000, 2, 0, 2]]) {
- expect(collaborationFrame(start)).toMatchObject({ active: source, handoff: { path, progress: 0 } });
+ for (const [start, end, source, destination, wire] of [[1500, 2250, 0, 1, 0], [3750, 4500, 1, 2, 1]]) {
+ expect(collaborationFrame(start)).toMatchObject({ active: source, handoff: { wire, progress: 0 } });
expect(collaborationFrame(end - 1).active).toBe(source);
expect(collaborationFrame(end)).toMatchObject({ active: destination, handoff: null });
expect(collaborationFrame(end).progress[destination]).toBe(0);
}
});
- it('finishes each card in 1.5 seconds and repeats the entire story together', () => {
+ it('travels one wire at a time and shows no pulse while a card works', () => {
+ expect(collaborationFrame(2600).handoff).toBeNull();
+ expect(collaborationFrame(1875).handoff).toEqual({ wire: 0, progress: 0.5 });
+ expect(collaborationFrame(6500).handoff).toEqual({ wire: 2, progress: 0.5 });
+ });
+ it('writes the skeleton line by line before the card reports complete', () => {
+ expect(collaborationFrame(2250).written[1]).toBe(0);
+ expect(collaborationFrame(2400).written[1]).toBe(2);
+ expect(collaborationFrame(2900).written[1]).toBe(WORK_LINES);
+ expect(collaborationFrame(2900).done[1]).toBe(false);
+ expect(collaborationFrame(3100)).toMatchObject({ active: 1, done: [true, true, false] });
+ });
+ it('keeps finished work on screen while the result returns to the PM', () => {
+ expect(collaborationFrame(6500)).toMatchObject({ done: [true, true, true], written: [WORK_LINES, WORK_LINES, WORK_LINES], returning: true, summary: false });
+ expect(collaborationFrame(8500)).toMatchObject({ active: 0, progress: [1, 1, 1], written: [WORK_LINES, WORK_LINES, WORK_LINES], summary: true, returning: true });
+ });
+ it('finishes each card inside its own step and repeats the entire story together', () => {
expect(collaborationFrame(1500).progress[0]).toBe(1);
expect(collaborationFrame(3750).progress[1]).toBe(1);
expect(collaborationFrame(6000).progress).toEqual([1, 1, 1]);
- expect(collaborationFrame(8500)).toMatchObject({ progress: [1, 1, 1], summary: true });
+ expect(COLLABORATION_DURATION).toBe(8900);
expect(collaborationFrame(8900)).toEqual(collaborationFrame(0));
});
- it('shows a completed collaboration with no pulse or active card in reduced motion', () => {
+ it('shows the completed collaboration with no pulse in reduced motion', () => {
for (const elapsed of [0, 1750, 4000, 6500, 8900]) {
- expect(collaborationFrame(elapsed, true)).toEqual({ active: null, handoff: null, progress: [1, 1, 1], summary: true });
+ expect(collaborationFrame(elapsed, true)).toEqual({
+ active: 0,
+ handoff: null,
+ progress: [1, 1, 1],
+ done: [true, true, true],
+ written: [WORK_LINES, WORK_LINES, WORK_LINES],
+ summary: true,
+ returning: true,
+ });
}
});
});
diff --git a/ui/src/components/onboarding/collaborationTimeline.ts b/ui/src/components/onboarding/collaborationTimeline.ts
index d80b5c3c8..9e05446fd 100644
--- a/ui/src/components/onboarding/collaborationTimeline.ts
+++ b/ui/src/components/onboarding/collaborationTimeline.ts
@@ -1,16 +1,71 @@
-export const COLLABORATION_DURATION = 8900;
export const ASSISTANT_ORDER = ['claude', 'codex', 'opencode'] as const;
export type AssistantId = typeof ASSISTANT_ORDER[number];
+/**
+ * The authored relay from the approved Welcome design: each assistant works for
+ * 1500ms, each handoff travels its wire, and the closing summary returns to the PM.
+ * A step keeps its SOURCE active while the pulse is in transit; the destination
+ * only activates once the pulse lands.
+ */
+const RELAY = [
+ { id: 'claude', active: 0, duration: 1500 },
+ { id: 'to-codex', active: 0, duration: 750, wire: 0 },
+ { id: 'codex', active: 1, duration: 1500 },
+ { id: 'to-opencode', active: 1, duration: 750, wire: 1 },
+ { id: 'opencode', active: 2, duration: 1500 },
+ { id: 'to-claude', active: 2, duration: 1000, wire: 2 },
+ { id: 'summary', active: 0, duration: 1900 },
+] as const;
+
+export const COLLABORATION_STEPS = RELAY.map((step, index) => {
+ const start = RELAY.slice(0, index).reduce((total, previous) => total + previous.duration, 0);
+ return { ...step, start, end: start + step.duration };
+});
+export const COLLABORATION_DURATION = COLLABORATION_STEPS[COLLABORATION_STEPS.length - 1].end;
+
+/** Each card fills its skeleton in 850ms; the rest of its turn holds the completed state. */
+export const WORK_CONTENT_DURATION = 850;
+/** Both the document and the code skeleton reveal six lines, 110ms apart. */
+export const WORK_LINES = 6;
+const WORK_STARTS = ASSISTANT_ORDER.map((_, index) => COLLABORATION_STEPS[index * 2].start);
+
+const clamp = (value: number) => Math.max(0, Math.min(1, value));
+
+export interface CollaborationFrame {
+ /** Index of the card that currently owns the work, or null when nothing is running. */
+ active: number | null;
+ /** Wire index the pulse is travelling, with its 0..1 position along that wire. */
+ handoff: { wire: number; progress: number } | null;
+ /** Skeleton fill 0..1 per card. */
+ progress: number[];
+ /** Completed work stays complete for the rest of the cycle, including the summary. */
+ done: boolean[];
+ /** Revealed skeleton lines per card. */
+ written: number[];
+ /** The closing phase, where the PM summarizes instead of restating its own work. */
+ summary: boolean;
+ /** True while the result is travelling back to, or being summarized by, the PM. */
+ returning: boolean;
+}
+
/** All cards and traveling pulses are projections of this one clock. */
-export function collaborationFrame(elapsed: number, reducedMotion = false) {
- const time = reducedMotion ? COLLABORATION_DURATION : elapsed % COLLABORATION_DURATION;
- const starts = [time >= 7000 ? 7000 : 0, 2250, 4500];
- const progress = starts.map((start) => Math.min(1, Math.max(0, (time - start) / 1500)));
- const active = reducedMotion ? null : time < 2250 ? 0 : time < 4500 ? 1 : time < 7000 ? 2 : 0;
- const handoff = time >= 1500 && time < 2250 ? { path: 0, progress: (time - 1500) / 750 }
- : time >= 3750 && time < 4500 ? { path: 1, progress: (time - 3750) / 750 }
- : time >= 6000 && time < 7000 ? { path: 2, progress: (time - 6000) / 1000 }
- : null;
- return { active, progress, handoff, summary: time >= 7000 };
+export function collaborationFrame(elapsed: number, reducedMotion = false): CollaborationFrame {
+ const time = reducedMotion ? COLLABORATION_DURATION - 1 : elapsed % COLLABORATION_DURATION;
+ const step = COLLABORATION_STEPS.find((candidate) => time < candidate.end)
+ ?? COLLABORATION_STEPS[COLLABORATION_STEPS.length - 1];
+ const worked = WORK_STARTS.map((start) => time - start);
+ const done = worked.map((value) => reducedMotion || value >= WORK_CONTENT_DURATION);
+ return {
+ active: step.active,
+ handoff: 'wire' in step && !reducedMotion
+ ? { wire: step.wire, progress: clamp((time - step.start) / step.duration) }
+ : null,
+ progress: worked.map((value, index) => (done[index] ? 1 : clamp(value / WORK_CONTENT_DURATION))),
+ done,
+ written: worked.map((value, index) => (done[index] ? WORK_LINES
+ : step.active === index ? Math.max(0, Math.min(WORK_LINES, Math.floor((value - 40) / 110) + 1))
+ : 0)),
+ summary: step.id === 'summary',
+ returning: step.id === 'to-claude' || step.id === 'summary',
+ };
}
diff --git a/ui/src/components/onboarding/motion.ts b/ui/src/components/onboarding/motion.ts
new file mode 100644
index 000000000..37a6186fa
--- /dev/null
+++ b/ui/src/components/onboarding/motion.ts
@@ -0,0 +1,68 @@
+import { useEffect, useState } from 'react';
+import { useReducedMotion } from 'framer-motion';
+
+/**
+ * Whether the document is being presented at all. An interval keeps firing in a
+ * background tab — throttled, so its deltas arrive in one lump — and a CSS
+ * animation keeps its own timeline running there too. Reading visibility here is
+ * what lets both stop together.
+ */
+function useDocumentVisible() {
+ const [visible, setVisible] = useState(() => typeof document === 'undefined' || !document.hidden);
+ useEffect(() => {
+ const read = () => setVisible(!document.hidden);
+ read();
+ document.addEventListener('visibilitychange', read);
+ return () => document.removeEventListener('visibilitychange', read);
+ }, []);
+ return visible;
+}
+
+/**
+ * Whether this particular composition is on screen. A hidden tab is only half the
+ * question: on a short window the diagram can sit entirely above the viewport while
+ * the document is perfectly visible, and its clock and CSS effects would keep running
+ * for nobody. `threshold: 0` is the same reading the incumbent observer in
+ * `vault-chat-requests` takes — any intersecting pixel counts — so a composition that
+ * is only partly scrolled in stays live rather than stuttering at the edge.
+ *
+ * Without an element or without the API (jsdom) this answers "on screen", so a
+ * consumer that never attaches the ref keeps the behaviour it had before. Nothing
+ * resets it when the effect cannot observe: an observer reports the element's current
+ * intersection as soon as it starts watching, so the only unobserved state that
+ * outlives the initial one is the element going away, and that is the unmount.
+ */
+function useElementOnScreen() {
+ const [element, setElement] = useState<HTMLElement | null>(null);
+ const [onScreen, setOnScreen] = useState(true);
+ useEffect(() => {
+ if (!element || typeof IntersectionObserver === 'undefined') return;
+ const observer = new IntersectionObserver(
+ ([entry]) => setOnScreen(entry.isIntersecting),
+ { threshold: 0 },
+ );
+ observer.observe(element);
+ return () => observer.disconnect();
+ }, [element]);
+ return [setElement, onScreen] as const;
+}
+
+/**
+ * The one answer to "is this onboarding animation running", used by the story and the
+ * access tiles so a reduced-motion preference, a hidden tab and being scrolled out of
+ * sight all stop it the same way. Each consumer attaches the returned `ref` to the
+ * element it draws in, so the two suspend independently: at desktop sizes both are
+ * normally on screen together, but on a short or narrow window they can have different
+ * viewport intersection, and each should answer for its own. There is no user-facing
+ * control here on purpose: the
+ * approved design has no playback toolbar, so this is lifecycle only. `running` also
+ * drives the diagram's `data-motion` attribute, which is how the CSS-owned effects (the
+ * skeleton shimmer and the test ticks) are held at their current frame rather than left
+ * to play on against a stopped clock.
+ */
+export function useOnboardingMotion() {
+ const reducedMotion = useReducedMotion() === true;
+ const documentVisible = useDocumentVisible();
+ const [ref, onScreen] = useElementOnScreen();
+ return { ref, reducedMotion, running: !reducedMotion && documentVisible && onScreen };
+}
diff --git a/ui/src/components/onboarding/onboarding.css b/ui/src/components/onboarding/onboarding.css
index d5971f80c..388b221bd 100644
--- a/ui/src/components/onboarding/onboarding.css
+++ b/ui/src/components/onboarding/onboarding.css
@@ -1,118 +1,641 @@
+/* Onboarding surface — Welcome and assistant setup.
+ *
+ * Geometry, fills and motion follow `avibe-docs/design_desktop.pen` and the authored
+ * animation in Show session `ses36vg559de2`. The values below are component-scoped on
+ * purpose: they encode exact approved design numbers without moving any global token.
+ *
+ * Widths are capped fluid, never fixed: the card grid uses percentage tracks and the
+ * diagram is sized from its own width, so card width, handoff gaps, diagram height and
+ * the stretched wire viewBox stay proportional at every container width. The owner
+ * accepted 1104 as the desktop cap; only the narrow bands choose a height directly.
+ */
.onboarding-shell {
+ --ob-card: linear-gradient(150deg, #151521, #101019);
+ --ob-card-border: #ffffff1c;
+ --ob-active-border: #5bffa059;
+ /* The reference's own exterior glow — a 28px, spread-less mint at #5BFFA060 — now
+ carried by one managed token instead of approximated by stacking two rungs of the
+ sized scale. The inset line is only the top highlight, not the glow. */
+ --ob-active-shadow: var(--shadow-glow-onboarding-mint), inset 0 1px 0 #5bffa012;
+ --ob-idle-dot: #4c5060;
+ --ob-skeleton: #ffffff12;
+ --ob-skeleton-strong: #ffffff28;
+ --ob-shimmer-soft: #ffffff08;
+ --ob-shimmer: #ffffff16;
+ --ob-line-number: #585c71;
+ --ob-code-violet: #a496e15c;
+ --ob-code-cyan: #67c2b75c;
+ --ob-check-bg: #ffffff05;
+ --ob-check-border: #5bffa044;
+ --ob-check-done: #5bffa012;
+ --ob-identity-line: #ffffff0e;
+ --ob-wire: #5bffa031;
+ --ob-port: #15281f;
+ --ob-port-border: #5bffa066;
+ --ob-pulse: #b5ffd4;
+ --ob-pulse-glow: #5bffa0;
+ --ob-caption: #697087;
+ --ob-tile-bg: #ffffff03;
+ --ob-tile-hover: #ffffff0a;
+ --ob-well: #ffffff04;
+ --ob-tile-label: #d3d7e2;
+
+ /* One content width for the header, the story and the assistant rows. 1104 is the
+ setup frame's own container (i3vw9 lays it out at x=48 of a 1200 frame); the owner
+ accepted it for the welcome too, whose blocks are authored at 880. Every dependent
+ number is therefore expressed as its ratio to 880 rather than re-typed: the cap
+ alone moves the whole composition and nothing can drift out of proportion.
+ At 1104 that yields 301.1 cards, a 1104x341.2 diagram and an 802.9 access span. */
+ --ob-content-w: 1104px;
+ /* 20px shell padding plus this bar is the setup's authored 64.5 top offset (IWQi6),
+ which it holds at every window height. The welcome is centred instead and reaches
+ the same 65 only at the design's own 756 content box. */
+ --ob-header-h: 45px;
+ /* The design's own side padding, so the cap is reached at exactly its 1200 frame. */
+ --ob-gutter: 48px;
+
background: var(--background);
color: var(--foreground);
height: var(--app-shell-h);
overflow-y: auto;
- padding: 20px 24px;
+ display: flex;
+ flex-direction: column;
+ padding: 20px var(--ob-gutter);
+}
+@media (prefers-color-scheme: light) {
+ :root:not([data-theme="dark"]) .onboarding-shell { --ob-theme: light; }
+}
+[data-theme="light"] .onboarding-shell { --ob-theme: light; }
+/* Both light blocks must stay value-identical, like the global theme's own pair. */
+@media (prefers-color-scheme: light) {
+ :root:not([data-theme="dark"]) .onboarding-shell {
+ --ob-card: #ffffff;
+ --ob-card-border: #08081212;
+ /* The light frame's own active card (waUhu): a #10B98160 edge over a 16/-4
+ #10B98170 halo, and no inset highlight — that top line is the dark card's
+ lit rim, and on white it reads as a seam. The halo is the same managed
+ token as dark; the token itself is what carries light's geometry. */
+ --ob-active-border: #10b98160;
+ --ob-active-shadow: var(--shadow-glow-onboarding-mint);
+ --ob-idle-dot: #5c6079;
+ --ob-skeleton: #08081214;
+ --ob-skeleton-strong: #08081224;
+ --ob-shimmer-soft: #08081204;
+ --ob-shimmer: #08081208;
+ --ob-line-number: #5c6079;
+ --ob-code-violet: #7c3aed24;
+ --ob-code-cyan: #0891b224;
+ --ob-check-bg: #eef1f7;
+ --ob-check-border: #aae6d2;
+ --ob-check-done: #10b98114;
+ --ob-identity-line: #08081214;
+ --ob-wire: #10b98124;
+ --ob-port: #10b98124;
+ --ob-port-border: #aae6d2;
+ /* Light keeps a light mint pulse; a darker green read as a smear on white. */
+ --ob-pulse: #6ee7b7;
+ --ob-pulse-glow: #5bffa080;
+ --ob-caption: #5c6079;
+ --ob-tile-bg: #ffffff;
+ --ob-tile-hover: #0808120a;
+ --ob-well: #eef1f780;
+ --ob-tile-label: #0a0a14;
+ }
}
+[data-theme="light"] .onboarding-shell {
+ --ob-card: #ffffff;
+ --ob-card-border: #08081212;
+ /* waUhu's edge and halo — see the prefers-color-scheme block above. */
+ --ob-active-border: #10b98160;
+ --ob-active-shadow: var(--shadow-glow-onboarding-mint);
+ --ob-idle-dot: #5c6079;
+ --ob-skeleton: #08081214;
+ --ob-skeleton-strong: #08081224;
+ --ob-shimmer-soft: #08081204;
+ --ob-shimmer: #08081208;
+ --ob-line-number: #5c6079;
+ --ob-code-violet: #7c3aed24;
+ --ob-code-cyan: #0891b224;
+ --ob-check-bg: #eef1f7;
+ --ob-check-border: #aae6d2;
+ --ob-check-done: #10b98114;
+ --ob-identity-line: #08081214;
+ --ob-wire: #10b98124;
+ --ob-port: #10b98124;
+ --ob-port-border: #aae6d2;
+ --ob-pulse: #6ee7b7;
+ --ob-pulse-glow: #5bffa080;
+ --ob-caption: #5c6079;
+ --ob-tile-bg: #ffffff;
+ --ob-tile-hover: #0808120a;
+ --ob-well: #eef1f780;
+ --ob-tile-label: #0a0a14;
+}
+
.onboarding-shell > header {
display: flex;
align-items: center;
- justify-content: space-between;
- max-width: 1104px;
+ justify-content: flex-end;
+ flex-shrink: 0;
+ height: var(--ob-header-h);
+ max-width: var(--ob-content-w);
+ width: 100%;
margin: 0 auto;
}
+/* `1 0 auto`: this box is never shorter than what it holds, so a composition taller
+ than the window pushes the shell into its own scroll rather than being clipped above
+ the fold — and centring a child inside it can never push that child off the top. */
.onboarding-shell-content {
+ flex: 1 0 auto;
display: flex;
- align-items: center;
- min-height: calc(100% - 44px);
- padding: 28px 0;
+ align-items: flex-start;
+ justify-content: center;
}
+/* The two steps are anchored differently because the design anchors them differently.
+ JuwcG and KIxnF centre the welcome in their frame; IWQi6 tops the setup out at its
+ own 64.5 padding. So the welcome's y is a RESULT of the window height — it is 65 at
+ the design's own 756 content box and lower in a taller one — while the setup's is the
+ position itself. Whichever is taller than the window scrolls from its top edge. */
+.onboarding-welcome { align-self: center; }
.onboarding-welcome, .onboarding-setup {
display: flex;
flex-direction: column;
align-items: center;
width: 100%;
- max-width: 880px;
+ max-width: var(--ob-content-w);
margin: 0 auto;
gap: 24px;
}
.onboarding-heading { text-align: center; width: 100%; }
+/* The live design's headline: 34/1.35/600 at -1.6 tracking (nodes XKQOx, Igagh and
+ hv9DA all agree), shared by the welcome and the setup title. */
.onboarding-heading h1, .onboarding-heading h2 {
font-size: 34px;
+ line-height: 1.35;
font-weight: 600;
- line-height: 1.2;
- letter-spacing: -0.5px;
+ letter-spacing: -1.6px;
+}
+.onboarding-heading p { margin-top: 10px; font-size: 14px; line-height: 22px; color: var(--muted); }
+
+/* ---- Collaboration story ------------------------------------------------ */
+
+.onboarding-story { position: relative; width: 100%; display: flex; align-items: flex-start; justify-content: center; }
+.onboarding-collaboration {
+ position: relative;
+ width: 100%;
+ max-width: var(--ob-content-w);
+ /* The diagram is sized from its own width, so the authored 880x272 proportion holds
+ at every width up to the cap, where it is the approved 1104x341.2. Narrow bands
+ set an explicit height instead: wrapped labels need more room than the proportion. */
+ aspect-ratio: 880 / 272;
+ height: var(--ob-diagram-h, auto);
+ container-type: inline-size;
+}
+.onboarding-collaboration-cards {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 27.272727%));
+ justify-content: space-between;
+ /* The cards occupy 228 of the 272 rows; the rest is the return wire's band. */
+ height: calc(100% * 228 / 272);
+ position: relative;
+ z-index: 1;
+ /* One design unit: the frames are drawn on an 880 box, so everything the card draws
+ is written as its authored number times this unit and stays proportional as the
+ diagram grows to the cap. Text and icons keep their own sizes on purpose — a card
+ that is a quarter taller should not read as a zoomed screenshot. */
+ --ob-u: calc(100cqw / 880);
}
-.onboarding-heading p { margin-top: 10px; font-size: 14px; color: var(--muted); }
-.onboarding-story { position: relative; width: 100%; }
-.onboarding-collaboration { position: relative; padding-bottom: 44px; }
-.onboarding-collaboration-cards { display: flex; justify-content: space-between; gap: 24px; }
.onboarding-collaboration-card {
- flex: 0 1 240px;
+ display: flex;
+ flex-direction: column;
+ height: 100%;
min-width: 0;
- height: 228px;
- border-radius: 16px;
- padding: 18px 20px;
- background: linear-gradient(150deg, var(--surface-2), var(--surface));
- transition: border-color 180ms, box-shadow 180ms;
-}
-.onboarding-collaboration-card[data-active="true"], .onboarding-assistant:hover, .onboarding-assistant:focus-within {
- border-color: color-mix(in srgb, var(--mint) 34%, transparent);
- box-shadow: var(--shadow-glow-lg-mint);
-}
-.onboarding-wires { position: absolute; inset: 0; width: 100%; height: 272px; pointer-events: none; }
-.onboarding-story-status { display: flex; align-items: center; gap: 7px; font-size: 10px; height: 14px; color: var(--muted); }
-.onboarding-story-status > span { flex: 1; white-space: nowrap; }
-.onboarding-status-glyph { width: 14px; height: 14px; flex-shrink: 0; }
-.onboarding-status-copy { animation: onboarding-status-in 250ms ease-out; }
-@keyframes onboarding-status-in { from { opacity: 0; } to { opacity: 1; } }
-.onboarding-skeleton { height: 134px; padding-top: 22px; display: flex; flex-direction: column; gap: 10px; }
-.onboarding-skeleton-row { display: flex; align-items: center; gap: 10px; height: 7px; }
-.onboarding-skeleton-line { display: block; height: 6px; border-radius: 3px; background: color-mix(in srgb, var(--foreground) 12%, transparent); }
-.onboarding-skeleton-claude .onboarding-skeleton-row:first-child .onboarding-skeleton-line { height: 9px; width: 55% !important; background: color-mix(in srgb, var(--foreground) 25%, transparent); }
-.onboarding-skeleton-codex .onboarding-skeleton-line { background: color-mix(in srgb, var(--cyan) 36%, transparent); }
-.onboarding-skeleton-codex .onboarding-skeleton-row:nth-child(even) .onboarding-skeleton-line { background: color-mix(in srgb, var(--violet) 36%, transparent); }
-.onboarding-code-number { font: 8px monospace; color: var(--muted); }
-.onboarding-skeleton-opencode { gap: 18px; }
-.onboarding-test-check { display: flex; width: 12px; height: 12px; border: 1px solid var(--border-strong); border-radius: 3px; color: var(--mint-ink); font-size: 10px; align-items: center; justify-content: center; flex-shrink: 0; }
-.onboarding-story-identity { display: flex; align-items: center; gap: 11px; padding-top: 16px; border-top: 1px solid var(--border); }
-.onboarding-story-identity strong { font-size: 14px; font-weight: 600; }
-.onboarding-story-identity > span:last-child { margin-left: auto; font-size: 11px; color: var(--muted); }
-.onboarding-story-caption { position: absolute; bottom: 0; left: 50%; transform: translateX(-50%); padding: 0 14px; background: var(--background); color: var(--muted); font-size: 10px; white-space: nowrap; }
-.onboarding-motion-controls { position: absolute; right: 0; bottom: -6px; display: flex; color: var(--muted); }
-.onboarding-access { max-width: 640px; width: 100%; padding: 16px 0; }
-.onboarding-access > p { text-align: center; font-size: 12px; color: var(--muted); margin-bottom: 14px; }
+ border-radius: calc(16 * var(--ob-u));
+ border: 1px solid var(--ob-card-border);
+ background: var(--ob-card);
+ padding: calc(18 * var(--ob-u)) calc(20 * var(--ob-u));
+ overflow: hidden;
+ transition: border-color 650ms, box-shadow 650ms;
+}
+.onboarding-collaboration-card[data-active="true"],
+.onboarding-assistant:hover, .onboarding-assistant:focus-within {
+ border-color: var(--ob-active-border);
+ box-shadow: var(--ob-active-shadow);
+}
+/* The card's 192 of content is authored as 14 status + 119 skeleton + 15 + 44 identity.
+ The skeleton is the flexible one, so anything the other three fail to claim pools
+ below the last bar — which is exactly what an unscaled 16px glyph and 28px logo did
+ at the cap. Both ends therefore reserve their authored share in design units, and the
+ skeleton keeps the 119 it was drawn at. Reserving rather than fixing also aligns the
+ three separators, since the rows above them are now the same height by construction. */
+.onboarding-story-status {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ flex-shrink: 0;
+ min-height: calc(14 * var(--ob-u));
+ color: var(--muted);
+ font-size: 10px;
+}
+.onboarding-status-icon { flex-shrink: 0; }
+.onboarding-status-text { white-space: nowrap; }
+.onboarding-status-enter { animation: onboarding-caption-enter 250ms ease-out both; }
+@keyframes onboarding-caption-enter { from { opacity: 0; } to { opacity: 1; } }
+/* 14, so the glyph fits the status row it sits in at the design's own scale instead
+ of forcing that row two pixels taller than the 14 it is drawn at. */
+.onboarding-status-glyph {
+ margin-left: auto;
+ width: 14px;
+ height: 14px;
+ flex-shrink: 0;
+ display: grid;
+ place-items: center;
+ color: var(--mint-ink);
+}
+.onboarding-status-dot { width: 5px; height: 5px; border-radius: 50%; background: var(--ob-idle-dot); }
+/* One ring, mounted from the first working frame through completion. */
+.onboarding-status-mark {
+ display: block;
+ width: 14px;
+ height: 14px;
+ overflow: visible;
+ stroke: currentColor;
+ stroke-linecap: round;
+ stroke-linejoin: round;
+}
+.onboarding-status-ring { stroke-width: 1.4; stroke-dasharray: 1; }
+.onboarding-status-check {
+ stroke-width: 1.8;
+ transform-box: view-box;
+ transform-origin: 8.5px 12.5px;
+ animation: onboarding-check-grow 300ms both;
+}
+@keyframes onboarding-check-grow {
+ 0% { opacity: 0; transform: scale(0); }
+ 10% { opacity: 1; }
+ 65% { transform: scale(1.16); }
+ 85% { transform: scale(0.96); }
+ 100% { opacity: 1; transform: scale(1); }
+}
+
+.onboarding-write-line {
+ opacity: 0;
+ clip-path: inset(0 100% 0 0);
+ transition: clip-path 100ms ease-out, opacity 80ms ease-out;
+}
+.onboarding-write-visible { opacity: 1; clip-path: inset(0 0 0 0); }
+.onboarding-skeleton { flex: 1; min-height: 0; padding-top: calc(17 * var(--ob-u)); position: relative; overflow: hidden; }
+.onboarding-bar {
+ display: block;
+ height: calc(6 * var(--ob-u));
+ border-radius: calc(3 * var(--ob-u));
+ background: var(--ob-skeleton);
+ flex-shrink: 0;
+}
+/* h5qtNn's own rhythm inside its 119 box: 17 above the heading, then 12 / 8 / 14 / 7 / 7
+ between the six lines, leaving 14 below the last one. The heading is excluded here
+ rather than left to lose: a class selector cannot outrank a child selector, so the
+ generic 8 silently ate the 12 this rule is the reason for. 14 is written as the
+ paragraph's own margin because it collapses with the 8 above it — the larger wins,
+ which is the gap the design draws between the two blocks. */
+.onboarding-skeleton-document > .onboarding-bar:not(.onboarding-bar-heading) { margin-bottom: calc(8 * var(--ob-u)); }
+.onboarding-bar-heading { height: calc(9 * var(--ob-u)); margin-bottom: calc(12 * var(--ob-u)); background: var(--ob-skeleton-strong); }
+.onboarding-skeleton-paragraph { display: flex; flex-direction: column; gap: calc(7 * var(--ob-u)); margin-top: calc(14 * var(--ob-u)); }
+.onboarding-bar-subheading { height: calc(7 * var(--ob-u)); background: var(--ob-card-border); }
+.onboarding-collaboration-card[data-state="working"] .onboarding-skeleton::after {
+ content: "";
+ position: absolute;
+ inset: 0;
+ transform: translateX(-110%);
+ background: linear-gradient(110deg, transparent 20%, var(--ob-shimmer-soft) 45%,
+ var(--ob-shimmer) 50%, var(--ob-shimmer-soft) 55%, transparent 80%);
+ animation: onboarding-shimmer 750ms ease-in-out both;
+ pointer-events: none;
+}
+@keyframes onboarding-shimmer { to { transform: translateX(110%); } }
+
+/* u3bGM: six 11-tall rows on a 16 pitch, 14 below the box top — and, like the document,
+ 14 left under the last one. The row is 11 because that is what its line number
+ occupies; the bars inside it are 6 and centre against that. */
+.onboarding-skeleton-code { display: flex; flex-direction: column; gap: calc(5 * var(--ob-u)); padding-top: calc(14 * var(--ob-u)); }
+.onboarding-code-row { display: flex; align-items: center; gap: calc(10 * var(--ob-u)); height: calc(11 * var(--ob-u)); }
+.onboarding-code-number { font-family: ui-monospace, monospace; font-size: 8px; line-height: 1; width: 7px; color: var(--ob-line-number); }
+.onboarding-code-bars { display: flex; align-items: center; gap: calc(6 * var(--ob-u)); flex: 1; min-width: 0; }
+.onboarding-bar-cyan { background: var(--ob-code-cyan); }
+.onboarding-bar-violet { background: var(--ob-code-violet); }
+
+/* xyNG1: four 12-tall rows on a 23 pitch, 17 below the box top. Fewer rows than the
+ other two, so this skeleton ends higher — the design's own asymmetry, not slack. */
+.onboarding-skeleton-tests { display: flex; flex-direction: column; gap: calc(11 * var(--ob-u)); padding-top: calc(17 * var(--ob-u)); }
+.onboarding-test-row { display: flex; align-items: center; gap: calc(9 * var(--ob-u)); }
+.onboarding-test-check {
+ height: calc(12 * var(--ob-u));
+ width: calc(12 * var(--ob-u));
+ flex-shrink: 0;
+ display: grid;
+ place-items: center;
+ border: 1px solid var(--ob-skeleton-strong);
+ border-radius: calc(3 * var(--ob-u));
+ background: var(--ob-check-bg);
+ color: transparent;
+}
+/* The four checks tick in order while the tests card is working. */
+.onboarding-collaboration-card[data-state="working"] .onboarding-test-check {
+ animation: onboarding-test-pass 340ms both;
+ animation-delay: calc(var(--test-index) * 160ms);
+}
+.onboarding-tests-done .onboarding-test-check {
+ color: var(--mint-ink);
+ border-color: var(--ob-check-border);
+ background: var(--ob-check-done);
+}
+@keyframes onboarding-test-pass {
+ 0%, 50% { color: transparent; border-color: var(--ob-skeleton-strong); background: var(--ob-check-bg); }
+ 100% { color: var(--mint-ink); border-color: var(--ob-check-border); background: var(--ob-check-done); }
+}
+
+/* 44 from the separator to the card's inner edge, 15 of clear space above it. The
+ 28px logo does not scale, so without the reserved height this block shrank as the
+ diagram grew and handed the difference to the skeleton above it. */
+.onboarding-story-identity {
+ display: flex;
+ align-items: center;
+ gap: 11px;
+ flex-shrink: 0;
+ min-height: calc(44 * var(--ob-u));
+ border-top: 1px solid var(--ob-identity-line);
+ padding-top: calc(16 * var(--ob-u));
+ margin-top: calc(15 * var(--ob-u));
+}
+.onboarding-story-identity > svg { flex-shrink: 0; }
+.onboarding-story-identity strong { font-size: 14px; font-weight: 550; letter-spacing: -0.3px; white-space: nowrap; }
+.onboarding-story-identity > span:last-child { margin-left: auto; font-size: 11px; color: var(--muted); white-space: nowrap; }
+
+.onboarding-wires { position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none; }
+.onboarding-wire { stroke: var(--ob-wire); stroke-width: 1; }
+.onboarding-port { fill: var(--ob-port); stroke: var(--ob-port-border); stroke-width: 1; }
+/* A single 16-unit segment of a 100-unit path: the pulse crosses once and leaves. */
+.onboarding-pulse-core, .onboarding-pulse-halo {
+ stroke-dasharray: 16 116;
+ stroke-dashoffset: 16;
+ stroke-linecap: round;
+ opacity: 0;
+}
+.onboarding-pulse-core { stroke: var(--ob-pulse); stroke-width: 1.6; }
+.onboarding-pulse-halo { stroke: var(--ob-pulse-glow); stroke-width: 4; }
+
+.onboarding-story-caption {
+ position: absolute;
+ bottom: -1px;
+ left: 50%;
+ transform: translateX(-50%);
+ padding: 0 12px;
+ background: var(--background);
+ color: var(--ob-caption);
+ font-size: 10px;
+ line-height: 18px;
+ white-space: nowrap;
+ transition: color 300ms;
+}
+.onboarding-story-caption[data-returning="true"] { color: var(--mint-ink); }
+
+/* ---- Access tiles -------------------------------------------------------- */
+
+/* The outer tile edges land on the two vertical legs of the return wire (x=120 and
+ x=760 of the 880 viewBox), so this block is 640/880 of the diagram — and of the
+ diagram as it currently is, not of the cap. Both are laid out in the same column, so
+ one percentage keeps the edges on the legs at every width: 802.9 at the 1104 cap,
+ 674.9 at a 928 content box, and so on down to the phone band. */
+.onboarding-access { width: calc(100% * 640 / 880); text-align: center; padding: 17px 0; }
+.onboarding-access > p { font-size: 12px; line-height: 20px; color: var(--muted); margin-bottom: 14px; }
.onboarding-access-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px 10px; list-style: none; }
-.onboarding-access-tile { display: flex; align-items: center; gap: 9px; min-height: 42px; padding: 0 10px; border-radius: 10px; border: 1px solid var(--border-strong); background: var(--surface); font-size: 12px; }
-.onboarding-access-icon { display: flex; align-items: center; justify-content: center; width: 28px; height: 28px; flex-shrink: 0; transition: transform 180ms; }
-.onboarding-access-tile:hover, .onboarding-access-tile:focus, .onboarding-access-tile[data-emphasis="true"] { background: color-mix(in srgb, var(--border) 50%, var(--surface)); }
-.onboarding-access-tile:hover .onboarding-access-icon, .onboarding-access-tile:focus .onboarding-access-icon, .onboarding-access-tile[data-emphasis="true"] .onboarding-access-icon { transform: scale(1.18); }
-.onboarding-access-tile:focus-visible { outline: 2px solid var(--ring); outline-offset: 3px; }
-.onboarding-setup { align-self: flex-start; padding-top: 24px; }
-.onboarding-assistants { width: 100%; display: flex; flex-direction: column; gap: 12px; }
-.onboarding-assistants-header { display: flex; justify-content: space-between; align-items: center; color: var(--muted); font-size: 13px; }
-.onboarding-assistant { transition: border-color 180ms, box-shadow 180ms; }
-.onboarding-assistant-main { display: flex; align-items: center; gap: 16px; min-height: 86px; padding: 16px 20px; }
-.onboarding-assistant-logo { width: 44px; height: 44px; display: flex; align-items: center; justify-content: center; background: var(--background); border-radius: 10px; flex-shrink: 0; }
+.onboarding-access-tile {
+ min-width: 0;
+ min-height: 42px;
+ padding: 0 10px;
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ border: 1px solid var(--border);
+ border-radius: 10px;
+ background: var(--ob-tile-bg);
+ color: var(--ob-tile-label);
+ font-size: 12px;
+ line-height: 18px;
+ text-align: left;
+ outline: none;
+ transition: background-color 180ms ease;
+}
+.onboarding-access-tile:hover, .onboarding-access-tile:focus-visible, .onboarding-access-tile[data-emphasis="true"] {
+ background: var(--ob-tile-hover);
+}
+.onboarding-access-tile:focus-visible { outline: 1px solid var(--mint); outline-offset: 2px; }
+.onboarding-access-icon {
+ height: 28px;
+ width: 28px;
+ flex-shrink: 0;
+ border-radius: 7px;
+ background: var(--ob-well);
+ display: grid;
+ place-items: center;
+ transition: transform 180ms ease;
+}
+.onboarding-access-tile:hover .onboarding-access-icon,
+.onboarding-access-tile:focus-visible .onboarding-access-icon,
+.onboarding-access-tile[data-emphasis="true"] .onboarding-access-icon { transform: scale(1.18); }
+
+/* ---- Primary action ------------------------------------------------------ */
+
+/* The reference draws this CTA as a flat mint fill — design.pen has no glow on any
+ button, and `brand` carries one at rest. The fill, the label pairing and the hover
+ stay the variant's; only the halo goes, which is presentation and nothing else. */
+.onboarding-primary-action {
+ box-shadow: none;
+ border-radius: 10px;
+ font-size: 13px;
+ font-weight: 600;
+ min-width: 144px;
+ height: 44px;
+ padding: 0 22px;
+ gap: 10px;
+}
+
+/* ---- Assistant setup ----------------------------------------------------- */
+
+/* The design spaces the section bar and every row by 12 (frame i3vw9: rows at 41, 141
+ and 241 below a 29 tall bar), so one gap owns both.
+ sNs1V draws this as a 360 slot holding a 329 bar-and-list, and the 24 below it is the
+ step's own gap. That 31 of remainder is the breathing space before the footer, so it
+ is reserved here rather than left over: a row that grows for an error or a wrapped
+ label takes it back, and the slot grows past 360 only once it is used up. */
+.onboarding-assistants { width: 100%; display: flex; flex-direction: column; gap: 12px; min-height: 360px; }
+.onboarding-assistants-header { display: flex; justify-content: space-between; align-items: center; }
+.onboarding-assistants-header h3 { font-size: 14px; font-weight: 600; color: var(--foreground); }
+/* The design's 88 is the row's own height, border included, so it lives here rather
+ than on the inner block; the row still grows when an error is shown. */
+.onboarding-assistant {
+ display: flex;
+ flex-direction: column;
+ min-height: 88px;
+ border-radius: 12px;
+ background: var(--surface-2);
+ transition: border-color 650ms, box-shadow 650ms;
+}
+/* The design's 20 is measured from the row's outer edge and the row carries a 1px
+ border, so the padding inside it is 19. */
+.onboarding-assistant-main { flex: 1; display: flex; align-items: center; gap: 16px; padding: 16px 19px; }
+.onboarding-assistant-logo {
+ width: 44px;
+ height: 44px;
+ flex-shrink: 0;
+ display: grid;
+ place-items: center;
+ border: 1px solid var(--border);
+ border-radius: 10px;
+ background: var(--ob-well);
+}
.onboarding-assistant-identity { flex: 1; min-width: 0; }
.onboarding-assistant-identity h3 { font-size: 15px; font-weight: 600; }
.onboarding-assistant-identity p { font-size: 12px; margin-top: 4px; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
.onboarding-assistant-status, .onboarding-assistant-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
-.onboarding-assistant-error { padding: 0 20px 16px; font-size: 12px; color: var(--destructive-ink); overflow-wrap: anywhere; }
+.onboarding-assistant-error { padding: 0 19px 16px; font-size: 12px; color: var(--destructive-ink); overflow-wrap: anywhere; }
.onboarding-assistant-error pre { margin-top: 8px; max-height: 160px; overflow: auto; white-space: pre-wrap; }
.onboarding-assistant-error summary { margin-top: 8px; cursor: pointer; }
.onboarding-setup-footer { display: flex; flex-direction: column; align-items: center; gap: 10px; }
-@media (max-width: 900px) {
+
+/* ---- Bands --------------------------------------------------------------- */
+
+/* Below the design width the collaboration keeps its proportions and only loses
+ height; the grid percentages carry the rest. A band's `--ob-diagram-h` is the whole
+ 272-row box, of which the cards keep 228 — so 250px is a 210px card. */
+@media (max-width: 1023px) {
+ .onboarding-shell { --ob-gutter: 24px; }
+}
+@media (max-width: 959px) {
+ .onboarding-shell { --ob-diagram-h: 250px; }
+ /* Below the proportional bands the card is sized by hand, so the interior returns to
+ its authored rhythm instead of following the diagram's width. */
+ .onboarding-collaboration-cards { --ob-u: 1px; }
+ /* A deliberate narrow-screen adaptation, not the design's number: the title drops to
+ 30 here, and its tracking follows it proportionally (-1.6 at 34 is -0.047em). */
+ .onboarding-heading h1, .onboarding-heading h2 { font-size: 30px; letter-spacing: -1.4px; }
+ .onboarding-collaboration-card { padding: 16px; }
+ .onboarding-story-identity { gap: 8px; padding-top: 12px; margin-top: 10px; }
+ .onboarding-story-identity strong { font-size: 13px; }
+ .onboarding-story-identity > span:last-child { font-size: 10px; }
+ .onboarding-story-identity > svg { width: 25px; height: 25px; }
+}
+/* Tablet portrait and below: the caption moves under the icon row so a full label
+ wraps instead of shrinking to an unreadable size. */
+@media (max-width: 767px) {
+ .onboarding-story-status { flex-wrap: wrap; row-gap: 4px; min-height: 32px; align-content: flex-start; }
+ .onboarding-status-text { order: 3; width: 100%; white-space: normal; font-size: 11px; line-height: 13px; }
+ .onboarding-story-identity { flex-wrap: wrap; gap: 6px; }
+ .onboarding-story-identity > span:last-child { margin-left: 0; width: 100%; }
.onboarding-assistant-main { flex-wrap: wrap; }
- .onboarding-assistant-identity p { white-space: normal; }
.onboarding-assistant-identity { flex-basis: calc(100% - 60px); }
.onboarding-assistant-actions { margin-left: auto; flex-wrap: wrap; }
}
-@media (max-width: 767px) {
- .onboarding-shell { padding: 16px; }
- .onboarding-heading h1, .onboarding-heading h2 { font-size: 28px; }
- .onboarding-collaboration-cards { flex-direction: column; align-items: center; gap: 24px; }
- .onboarding-collaboration-card { width: min(100%, 320px); flex: none; }
- .onboarding-wires { display: none; }
- .onboarding-collaboration-card { position: relative; }
- .onboarding-collaboration-card + .onboarding-collaboration-card::before { content: ''; position: absolute; height: 24px; width: 1px; background: var(--border-strong); top: -25px; left: 50%; }
- .onboarding-access-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
- .onboarding-assistant-main { gap: 12px; padding: 16px; }
- .onboarding-assistant-actions { margin-left: 0; }
- .onboarding-motion-controls { bottom: -28px; }
+@media (max-width: 599px) {
+ .onboarding-shell { --ob-gutter: 16px; --ob-diagram-h: 300px; }
+ /* Phones loosen rather than follow the proportion: -1.2 would be the 34/-1.6 ratio at
+ this size, and tight tracking is exactly what costs legibility on a small screen. */
+ .onboarding-heading h1, .onboarding-heading h2 { font-size: 25px; line-height: 1.4; letter-spacing: -0.8px; }
+ .onboarding-heading p { font-size: 12px; line-height: 20px; }
+ .onboarding-welcome, .onboarding-setup { gap: 20px; }
+ .onboarding-collaboration-card { padding: 10px 8px; border-radius: 10px; }
+ /* The kind glyph stays: it is the one mark that says which of the three kinds of work
+ a card is doing, and at 13px it costs a third of a row it already reserves. */
+ .onboarding-story-status { min-height: 46px; }
+ .onboarding-skeleton { padding-top: 12px; }
+ .onboarding-bar { height: 4px; }
+ .onboarding-bar-heading { height: 6px; margin-bottom: 8px; }
+ .onboarding-skeleton-document > .onboarding-bar:not(.onboarding-bar-heading) { margin-bottom: 5px; }
+ .onboarding-skeleton-paragraph { gap: 5px; margin-top: 8px; }
+ .onboarding-bar-subheading { height: 5px; }
+ .onboarding-skeleton-code { gap: 6px; padding-top: 12px; }
+ .onboarding-code-row { gap: 4px; height: 6px; }
+ .onboarding-code-number { font-size: 6px; }
+ .onboarding-code-bars { gap: 3px; padding-left: 0 !important; }
+ .onboarding-skeleton-tests { gap: 7px; padding-top: 12px; }
+ .onboarding-test-row { gap: 5px; }
+ .onboarding-test-check { width: 10px; height: 10px; border-radius: 2px; }
+ .onboarding-test-check svg { width: 8px; height: 8px; }
+ /* One arrangement for all three cards, rather than whichever one each name's length
+ produces. A card is ~62px wide here, so "Claude Code" wraps and "Codex" does not:
+ free flex wrapping therefore put two logos above their names and the third beside
+ one, and left the three separators as much as 21px apart. An explicit stack — logo,
+ name, role, each on its own row — with the name's box holding the two lines the
+ longest of them needs makes the three identities the same height by construction,
+ and the skeleton above absorbs the difference, so the separators line up. Nothing
+ is truncated or scaled to fit: both lines of a wrapped name are shown. */
+ .onboarding-story-identity {
+ display: grid;
+ grid-template-columns: minmax(0, 1fr);
+ justify-items: start;
+ padding-top: 9px;
+ margin-top: 8px;
+ gap: 4px;
+ }
+ .onboarding-story-identity > svg { width: 20px; height: 20px; }
+ .onboarding-story-identity strong {
+ font-size: 11px;
+ line-height: 14px;
+ letter-spacing: -0.4px;
+ white-space: normal;
+ min-height: 28px;
+ }
+ .onboarding-story-identity > span:last-child { font-size: 10px; line-height: 13px; min-height: 13px; }
+ /* The one width that deliberately leaves the wire relation: two columns of 640/880 of
+ a phone would be ~200px of tiles inside a 360px screen, so below this band the
+ block takes the full width and the tiles stay a readable target. */
+ .onboarding-access { width: 100%; padding: 10px 0; }
+ .onboarding-access-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; }
+ .onboarding-access-tile { min-height: 44px; padding: 0 9px; gap: 8px; }
+ /* Small screens let the row follow its wrapped contents instead of the design's 88. */
+ .onboarding-assistant { min-height: 0; }
+ .onboarding-assistant-main { gap: 12px; padding: 14px 16px; }
+ .onboarding-assistant-logo { width: 36px; height: 36px; }
+ .onboarding-assistant-identity { flex-basis: calc(100% - 48px); }
+ .onboarding-assistant-identity p { white-space: normal; }
+ .onboarding-assistant-status, .onboarding-assistant-actions { margin-left: 0; flex-wrap: wrap; }
+}
+/* The narrowest supported width still shows every label; English needs a third line. */
+@media (max-width: 374px) {
+ .onboarding-shell { --ob-diagram-h: 320px; }
+ .onboarding-story-status { min-height: 62px; }
+}
+/* A short window scrolls. There used to be a `max-height: 760px` rule here that took
+ the step gaps from 24 to 16 and squeezed the access block, which bought roughly 30px
+ and spent the design's own spacing to do it — at 1200x800, the reference's own frame
+ size, where nothing was wrong. Whitespace is the composition; scrolling is an
+ accepted outcome. Only the narrow bands adapt, and they adapt by width. */
+
+/* ---- Stopping ------------------------------------------------------------ */
+
+/* Pausing has to stop what is being drawn, not only the clock the cards are read from.
+ The skeleton shimmer and the four test ticks are CSS animations on their own
+ timeline, which `page.clock`-style time control and a frozen React tree both leave
+ running; the same is true of a hidden tab, where they would play on unseen and
+ reappear mid-sweep. `paused` holds each of them at its current frame, so resuming
+ continues the same sweep instead of jumping to wherever wall-clock time had got to. */
+/* `!important` for the same reason the reduced-motion block below uses it: this is a
+ lifecycle override, and no authored rule should be able to out-specify "the tab is not
+ being presented". Without it the shimmer kept running — its own rule carries a class
+ more than this one, and the `animation` shorthand it uses resets play state to
+ running, so the longest effect on the screen was the one this never reached. */
+.onboarding-collaboration[data-motion="paused"],
+.onboarding-collaboration[data-motion="paused"] *,
+.onboarding-collaboration[data-motion="paused"] *::before,
+.onboarding-collaboration[data-motion="paused"] *::after {
+ animation-play-state: paused !important;
}
+
@media (prefers-reduced-motion: reduce) {
- .onboarding-shell *, .onboarding-shell *::before { animation: none !important; transition: none !important; }
+ .onboarding-shell *, .onboarding-shell *::before, .onboarding-shell *::after {
+ animation: none !important;
+ transition: none !important;
+ }
.onboarding-access-icon { transform: none !important; }
+ .onboarding-pulse-core, .onboarding-pulse-halo { stroke-dasharray: none; }
}
diff --git a/ui/src/components/steps/AgentDetection.tsx b/ui/src/components/steps/AgentDetection.tsx
index a6a2ff885..ab868325b 100644
--- a/ui/src/components/steps/AgentDetection.tsx
+++ b/ui/src/components/steps/AgentDetection.tsx
@@ -478,7 +478,9 @@ export const AgentDetection: React.FC<AgentDetectionProps> = ({ data, onNext, on
<div className="onboarding-assistants">
<div className="onboarding-assistants-header">
<h3>{t('onboarding.setup.assistants')}</h3>
- <Button type="button" variant="ghost" size="sm" onClick={() => void detectAll()}
+ {/* n4ATm draws this as an outlined control on its own surface, not a bare
+ text button: `secondary` is that pair, and `xs` its 12px/12px metrics. */}
+ <Button type="button" variant="secondary" size="xs" onClick={() => void detectAll()}
disabled={isAnyInstalling || Object.values(detectingAgents).some(Boolean)}>
<RefreshCw size={14} />{t('agentDetection.rescan')}
</Button>
@@ -513,9 +515,10 @@ export const AgentDetection: React.FC<AgentDetectionProps> = ({ data, onNext, on
onSetup={() => void permission.setupPermission()} className="w-full" />
{providerDialog}
<div className="onboarding-setup-footer">
- <Button type="button" variant="brand" className="h-11 min-w-36" onClick={() => void handlePrimaryAction()}
+ <Button type="button" variant="brand" className="group onboarding-primary-action" onClick={() => void handlePrimaryAction()}
disabled={!canContinue || syncing}>
- {t('common.continue')}<ArrowRight size={16} />
+ {t('common.continue')}
+ <ArrowRight size={16} className="motion-safe:transition-transform motion-safe:duration-180 motion-safe:group-hover:translate-x-1" />
</Button>
{opencodeNeedsPermission && <p className="text-center text-xs text-gold-ink">{t('agentDetection.permissionGateHint')}</p>}
{onBack && <Button type="button" variant="ghost" size="sm" disabled={syncing} onClick={() => onBack({ agents })}><ArrowLeft size={14} />{t('common.back')}</Button>}
diff --git a/ui/src/components/steps/Welcome.tsx b/ui/src/components/steps/Welcome.tsx
index 741478317..7a1b91980 100644
--- a/ui/src/components/steps/Welcome.tsx
+++ b/ui/src/components/steps/Welcome.tsx
@@ -17,7 +17,6 @@ interface WelcomeProps {
export function Welcome({ data, onNext }: WelcomeProps) {
const { t } = useTranslation();
const api = useApi();
- const [paused, setPaused] = useState(false);
const [pending, setPending] = useState(false);
const [error, setError] = useState<string | null>(null);
const busy = useRef(false);
@@ -46,9 +45,9 @@ export function Welcome({ data, onNext }: WelcomeProps) {
<h1>{t('onboarding.welcome.title')}</h1>
<p>{t('onboarding.welcome.subtitle')}</p>
</header>
- <CollaborationStory paused={paused} onPausedChange={setPaused} />
- <AccessTiles paused={paused} />
- <Button type="button" variant="brand" className="group h-11 min-w-36" onClick={() => void start()} disabled={pending}>
+ <CollaborationStory />
+ <AccessTiles />
+ <Button type="button" variant="brand" className="group onboarding-primary-action" onClick={() => void start()} disabled={pending}>
{t(pending ? 'onboarding.welcome.detecting' : error ? 'common.retry' : 'onboarding.welcome.getStarted')}
{pending ? <RefreshCw size={16} className="motion-safe:animate-spin" /> : <ArrowRight size={16} className="motion-safe:transition-transform motion-safe:duration-180 motion-safe:group-hover:translate-x-1" />}
</Button>
diff --git a/ui/src/i18n/en.json b/ui/src/i18n/en.json
index 60f871536..2e418baea 100644
--- a/ui/src/i18n/en.json
+++ b/ui/src/i18n/en.json
@@ -5215,13 +5215,10 @@
"label": "Assistants working together",
"description": "Claude Code plans the work, Codex builds it, OpenCode tests it, and Claude Code summarizes the result.",
"caption": "Plan · Build · Test · Deliver",
- "pause": "Pause animation",
- "play": "Play animation",
- "replay": "Replay animation",
+ "returnCaption": "Tests passed · back to the PM",
"claude": {
"name": "Claude Code",
"role": "PM",
- "waiting": "Planning the work",
"working": "Writing the project brief",
"complete": "Project brief ready",
"summary": "Summarizing the delivery"
@@ -5229,14 +5226,12 @@
"codex": {
"name": "Codex",
"role": "Developer",
- "waiting": "Waiting for the brief",
"working": "Writing code",
"complete": "Implementation ready"
},
"opencode": {
"name": "OpenCode",
"role": "Tester",
- "waiting": "Waiting for the code",
"working": "Writing and running tests",
"complete": "All tests passed"
}
diff --git a/ui/src/i18n/zh.json b/ui/src/i18n/zh.json
index bfe13ad46..5f4926048 100644
--- a/ui/src/i18n/zh.json
+++ b/ui/src/i18n/zh.json
@@ -5215,28 +5215,23 @@
"label": "助手接力协作",
"description": "Claude Code 规划任务,Codex 编写代码,OpenCode 执行测试,最后由 Claude Code 汇总交付。",
"caption": "规划 · 开发 · 测试 · 交付",
- "pause": "暂停动画",
- "play": "播放动画",
- "replay": "重新播放动画",
+ "returnCaption": "测试通过,回传 PM",
"claude": {
"name": "Claude Code",
"role": "PM",
- "waiting": "规划任务",
"working": "编写需求文档",
"complete": "需求文档已就绪",
- "summary": "汇总交付结果"
+ "summary": "汇总结果,完成交付"
},
"codex": {
"name": "Codex",
"role": "开发",
- "waiting": "等待需求文档",
"working": "编写功能代码",
"complete": "功能代码已就绪"
},
"opencode": {
"name": "OpenCode",
"role": "测试",
- "waiting": "等待功能代码",
"working": "编写并执行用例",
"complete": "测试全部通过"
}
diff --git a/ui/src/index.css b/ui/src/index.css
index 24d1b8272..96b2461e9 100644
--- a/ui/src/index.css
+++ b/ui/src/index.css
@@ -188,6 +188,27 @@
--shadow-glow-xl-mint: 0 0 48px -12px rgba(91, 255, 160, 0.44);
+ /* `onboarding` is the active-card halo of the approved onboarding reference, the
+ one the owner pointed at: a centred 28px mint at #5BFFA060, with no spread and
+ brighter than the sized rungs carry. It is a role rather than a rung because
+ both of those departures are the reference's, not the scale's -- reaching it by
+ stacking `xl` and `lg` was an approximation of an explicit value.
+ `37.6%` is that hex's own alpha: 0x60 is 96/255.
+
+ It is the one role the design draws at two sizes, because the two frames drew
+ it separately: Light's active card (node waUhu) is 16/-4 at #10B98170, which is
+ the sized scale's own `sm` geometry and alpha. The hue needs nothing for that
+ -- `var(--mint)` already follows whichever mint the theme declares, the way
+ `wire` does -- but blur, spread and alpha are numbers, and a number cannot
+ follow a palette. They are named here and re-anchored beside the rest of the
+ light palette, which is the shape `--brand-glow-blur` already uses and the only
+ one that renders: this block is `@theme inline`, so Tailwind substitutes the
+ value below into the utilities at build time and a later override of THIS name
+ would compile to nothing while looking correct in the file. */
+ --shadow-glow-onboarding-mint:
+ 0 0 var(--onboarding-glow-blur) var(--onboarding-glow-spread)
+ color-mix(in srgb, var(--mint) var(--onboarding-glow-alpha), transparent);
+
--shadow-glow-cta-mint: 0 0 var(--brand-glow-blur) -4px rgba(91, 255, 160, 0.6);
--shadow-glow-cta-cyan: 0 0 var(--brand-glow-blur) -4px rgba(63, 224, 229, 0.6);
--shadow-glow-cta-violet: 0 0 var(--brand-glow-blur) -4px rgba(124, 91, 255, 0.6);
@@ -279,6 +300,13 @@
because it is the one part of that glow that differs per theme. */
--brand-glow-blur: 16px;
+ /* Geometry and alpha of the onboarding active-card halo, for the same reason the
+ CTA blur is here: they are the parts of that glow that differ per theme, and
+ the token itself is inlined into its utilities and so cannot be re-declared. */
+ --onboarding-glow-blur: 28px;
+ --onboarding-glow-spread: 0px;
+ --onboarding-glow-alpha: 37.6%;
+
/* Colour of the card wash shadows (`--shadow-mint-card*`). design.pen writes it
as the frame's own brand mint at 0.078, which is why it is the one part of
those shadows that moves between themes. */
@@ -437,6 +465,14 @@
/* Wider CTA glow than dark: the same neon spreads far less over a white card,
so 16px read as almost nothing here (owner decision 2026-08-14). */
--brand-glow-blur: 20px;
+
+ /* The Light frame's own active card (waUhu) draws 16px at -4px spread and
+ #10B98170 -- the sized scale's `sm` geometry and its 0.44 alpha, not dark's
+ spreadless 28. Only these numbers are re-anchored; the hue stays `var(--mint)`,
+ which this block has already swapped to the light brand. */
+ --onboarding-glow-blur: 16px;
+ --onboarding-glow-spread: -4px;
+ --onboarding-glow-alpha: 44%;
}
}
@@ -542,6 +578,12 @@
/* Wider CTA glow than dark: the same neon spreads far less over a white card,
so 16px read as almost nothing here (owner decision 2026-08-14). */
--brand-glow-blur: 20px;
+
+ /* Light's own active-card geometry - see the prefers-color-scheme block above.
+ Both light blocks must stay value-identical. */
+ --onboarding-glow-blur: 16px;
+ --onboarding-glow-spread: -4px;
+ --onboarding-glow-alpha: 44%;
}
html,