Onboarding v4: design feedback round 2

special-pages/pages/onboarding/app/v4/components/Bubble.js

@@ -15,6 +15,7 @@ import { ProgressIndicator } from './ProgressIndicator';
  * @property {boolean} [exiting] - When true, fades out the container via CSS animation
  * @property {() => void} [onExitComplete] - Called when the fade-out animation ends
  * @property {import('../data/data-types').Progress} [progress] - When provided, renders a progress badge pinned to the bubble's top edge
+ * @property {number} [fadeInDelay] - Delay in ms before the fade-in animation starts (default 400ms via CSS)
  */
 
 /**
@@ -48,6 +49,7 @@ export function Bubble({
     exiting = false,
     onExitComplete,
     progress,
+    fadeInDelay,
     ...props
 }) {
     const { isReducedMotion } = useEnv();
@@ -142,6 +144,7 @@ export function Bubble({
             <div
                 ref={containerCallback}
                 class={cn(styles.container, isMounted.current && (exiting ? styles.fadeOut : styles.fadeIn))}
+                style={fadeInDelay !== undefined ? { '--fade-in-delay': `${fadeInDelay}ms` } : undefined}
                 onAnimationEnd={complete}
             >
                 <div ref={contentRef} class={styles.content}>

special-pages/pages/onboarding/app/v4/components/Bubble.module.css

@@ -37,7 +37,7 @@
 }
 
 .fadeIn {
-    animation: fade-in 267ms cubic-bezier(0.66, 0, 0.34, 1) 400ms backwards;
+    animation: fade-in 267ms cubic-bezier(0.66, 0, 0.34, 1) var(--fade-in-delay, 400ms) backwards;
 }
 
 /* Clip wrapper for bottom-left tail — overflow creates the tuck/untuck effect */

special-pages/pages/onboarding/app/v4/components/DuckPlayerContent.js

@@ -74,6 +74,8 @@ function DuckPlayerDefault({ advance }) {
     const videosRef = useRef(/** @type {Record<DPTarget, HTMLVideoElement | null>} */ ({ with: null, without: null }));
 
     const [state, setState] = useState(/** @type {DPState} */ ({ target: 'with', phase: 'initial', reverse: false }));
+    const stateRef = useRef(state);
+    stateRef.current = state;
 
     /** @type {(target: DPTarget) => DPTarget} */
     const flip = (target) => (target === 'with' ? 'without' : 'with');
@@ -90,9 +92,11 @@ function DuckPlayerDefault({ advance }) {
         }
         video.currentTime = 0;
         try {
+            /** @type {Promise<void>} */
+            const frameReady = new Promise((resolve) => video.requestVideoFrameCallback(() => resolve()));
             await video.play();
+            await frameReady;
         } catch (error) {
-            // Ignore errors - we can assume that our browsers support playback
             console.error(error);
         }
     };
@@ -102,20 +106,20 @@ function DuckPlayerDefault({ advance }) {
         if (video) video.currentTime = 0;
     };
 
-    // Auto-play after bubble entry animation (400ms delay + 267ms duration = 667ms)
+    // Auto-play after bottom bubble entry animation (650ms delay + 267ms duration = 917ms)
     useEffect(() => {
         const id = setTimeout(
             () => {
                 play(videoFor('with'));
                 setState((prev) => ({ ...prev, phase: isReducedMotion ? 'settled' : 'playing' }));
             },
-            isReducedMotion ? 0 : 667,
+            isReducedMotion ? 0 : 917,
         );
         return () => clearTimeout(id);
     }, []); // exclude isReducedMotion from deps — must not re-fire if reduced motion changes after mount
 
-    const toggle = () => {
-        const { target, phase, reverse } = state;
+    const toggle = async () => {
+        const { target, phase, reverse } = stateRef.current;
         if (phase === 'initial') {
             // Queue or cancel a reverse so auto-play will switch to "without" once the "with" video ends
             setState({ target, phase, reverse: !reverse });
@@ -124,18 +128,19 @@ function DuckPlayerDefault({ advance }) {
             if (!reverse) reset(videoFor(flip(target)));
             setState({ target, phase: 'playing', reverse: !reverse });
         } else {
-            // Settled: switch to the other video
+            // Settled: play the other video, wait for its first frame, then switch visibility
             const next = flip(target);
-            play(videoFor(next));
+            await play(videoFor(next));
             setState({ target: next, phase: isReducedMotion ? 'settled' : 'playing', reverse: false });
         }
     };
 
-    const end = () => {
-        if (state.reverse) {
-            // A reverse was queued — play the other video now
-            const next = flip(state.target);
-            play(videoFor(next));
+    const end = async () => {
+        const { reverse, target } = stateRef.current;
+        if (reverse) {
+            // A reverse was queued — play the other video, wait for its first frame, then switch
+            const next = flip(target);
+            await play(videoFor(next));
             setState({ target: next, phase: 'playing', reverse: false });
         } else {
             // No reverse — just settle on the current video

special-pages/pages/onboarding/app/v4/components/DuckPlayerContent.module.css

@@ -41,7 +41,8 @@
         position: absolute;
         top: 0;
         left: 0;
-        visibility: hidden;
+        opacity: 0;
+        pointer-events: none;
     }
 }
 

special-pages/pages/onboarding/app/v4/components/GetStartedContent.module.css

@@ -21,7 +21,7 @@
     font-size: calc(18 * var(--px-in-rem));
     font-weight: 400;
     line-height: calc(22 * var(--px-in-rem));
-    text-align: center;
+    text-align: left;
     color: var(--ds-text-primary);
     word-wrap: break-word;
     text-box-trim: trim-both;

special-pages/pages/onboarding/app/v4/components/MakeDefaultContent.js

@@ -13,6 +13,9 @@ import { useFlip } from '../hooks/useFlip';
 import cn from 'classnames';
 import styles from './MakeDefaultContent.module.css';
 
+/** @type {string|null} */
+const bubbleFadeInDelayOverride = new URLSearchParams(window.location.search).get('bubbleFadeInDelay');
+
 /**
  * Top bubble content for the makeDefaultSingle step.
  * Shows title (changes after user makes default), comparison table, and Skip/Make Default buttons.
@@ -78,6 +81,11 @@ export function MakeDefaultContent({ advance, updateSystemValue }) {
         })();
     };
 
+    const defaultBubbleDelay = 400;
+    const defaultOffset = 250;
+    const parsedOffset = bubbleFadeInDelayOverride ? Number.parseInt(bubbleFadeInDelayOverride, 10) : defaultOffset;
+    const staggerDelay = defaultBubbleDelay + (Number.isNaN(parsedOffset) ? defaultOffset : parsedOffset);
+
     return (
         <Container class={styles.root}>
             <div class={styles.titleContainer}>
@@ -95,17 +103,19 @@ export function MakeDefaultContent({ advance, updateSystemValue }) {
                 />
             </div>
 
-            <ComparisonTable />
+            <div class={styles.content} style={{ '--stagger-delay': `${staggerDelay}ms` }}>
+                <ComparisonTable />
 
-            <div class={styles.actions}>
-                {skipButtonMounted && (
-                    <Button buttonRef={skipButtonRef} class={styles.skipButton} variant="secondary" onClick={advance}>
-                        {t('skipButton')}
+                <div class={styles.actions}>
+                    {skipButtonMounted && (
+                        <Button buttonRef={skipButtonRef} class={styles.skipButton} variant="secondary" onClick={advance}>
+                            {t('skipButton')}
+                        </Button>
+                    )}
+                    <Button buttonRef={primaryButtonRef} disabled={isPending} onClick={showSkipButton ? enableDefaultBrowser : advance}>
+                        {showSkipButton ? t('makeDefaultButton') : t('nextButton')}
                     </Button>
-                )}
-                <Button buttonRef={primaryButtonRef} disabled={isPending} onClick={showSkipButton ? enableDefaultBrowser : advance}>
-                    {showSkipButton ? t('makeDefaultButton') : t('nextButton')}
-                </Button>
+                </div>
             </div>
         </Container>
     );

special-pages/pages/onboarding/app/v4/components/MakeDefaultContent.module.css

@@ -4,6 +4,7 @@
 
 .titleContainer {
     position: relative;
+    align-self: stretch;
 }
 
 .title {
@@ -22,6 +23,15 @@
     }
 }
 
+.content {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    align-self: stretch;
+    gap: var(--sp-8); /* 32px — match Container gap */
+    animation: stagger-fade-in 267ms cubic-bezier(0.66, 0, 0.34, 1) var(--stagger-delay, 650ms) backwards;
+}
+
 .actions {
     position: relative;
     display: flex;
@@ -38,3 +48,14 @@
 .skipButton {
     flex: 1;
 }
+
+@keyframes stagger-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .content {
+        animation: none;
+    }
+}

special-pages/pages/onboarding/app/v4/components/SingleStep.js

@@ -8,6 +8,9 @@ import styles from './SingleStep.module.css';
 /** @type {string|null} */
 const bubbleWidthOverride = new URLSearchParams(window.location.search).get('bubbleWidth');
 
+/** @type {string|null} */
+const bubbleFadeInDelayOverride = new URLSearchParams(window.location.search).get('bubbleFadeInDelay');
+
 /**
  * Main layout component for v4 steps.
  * Steps with bubbles use absolute positioning; the layout measures bubble heights.
@@ -67,6 +70,16 @@ export function SingleStep() {
                 exiting={globalState.exiting}
                 onExitComplete={topBubble ? undefined : advance}
                 progress={showProgress && !topBubble ? progress : undefined}
+                fadeInDelay={
+                    topBubble
+                        ? (() => {
+                              const defaultTopDelay = 400; // Default fade-in delay from CSS
+                              const defaultOffset = 250; // Default 250ms offset between top and bottom
+                              const offset = bubbleFadeInDelayOverride ? Number.parseInt(bubbleFadeInDelayOverride, 10) : defaultOffset;
+                              return defaultTopDelay + (Number.isNaN(offset) ? defaultOffset : offset);
+                          })()
+                        : undefined
+                }
             >
                 {bottomBubble?.content}
             </Bubble>

special-pages/pages/onboarding/app/v4/components/StepHeader.module.css

@@ -16,7 +16,7 @@
     font-size: var(--sp-6); /* 24px */
     font-weight: 700;
     line-height: var(--sp-7); /* 28px */
-    text-align: center;
+    text-align: left;
     white-space: pre-line;
     color: var(--ds-text-primary);
     margin: 0;
@@ -29,7 +29,7 @@
     font-size: calc(18 * var(--px-in-rem));
     font-weight: 400;
     line-height: calc(22 * var(--px-in-rem));
-    text-align: center;
+    text-align: left;
     white-space: pre-line;
     color: var(--ds-text-primary);
     margin: 0;

special-pages/pages/onboarding/app/v4/components/Title.module.css

@@ -3,7 +3,7 @@
     font-size: var(--sp-6); /* 24px */
     font-weight: 700;
     line-height: var(--sp-7); /* 28px */
-    text-align: center;
+    text-align: left;
     color: var(--ds-text-primary);
     word-wrap: break-word;
     text-box-trim: trim-both;

special-pages/pages/onboarding/integration-tests/onboarding.v4.spec.js

@@ -238,7 +238,7 @@ test.describe('onboarding v4', () => {
             // Simulate disabled video ending → reducer plays enabled video (toWithDuckPlayer)
             await disabledVideo.dispatchEvent('ended');
             await expect(enabledVideo).toBeVisible();
-            await expect(disabledVideo).not.toBeVisible();
+            await expect(disabledVideo).toHaveCSS('opacity', '0');
             await expect(page.getByRole('button', { name: 'See Without Duck Player' })).toBeVisible();
 
             // Simulate enabled video ending → withDuckPlayer