Team Lead first-run onboarding UX polish

[ChesterSchendel]

Found during the 2026-05-29 prod end-to-end test. The invite → accept → tier-flip pipeline works on prod; these are UX/copy refinements on top of it.

Items

1. Post-accept landing page. A newly invited Team Lead lands on the Home page, not the Dashboard. Should route to /dashboard (or /dashboard/team) after accepting + signing in. Governed by the after-sign-in redirect (NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL / invite-accept target). Related to existing task Add hyperlinks throughout blog posts #8.

2. "Welcome back." shown to first-time users. src/app/dashboard/page.tsx line 495: {firstName ? \Hi, ${firstName}.` : "Welcome back."}`. Two stacked problems:

   • The fallback copy "Welcome back." is a returning-user phrase — wrong for a first-timer.
   • Root cause of the fallback firing: the Team Lead's first/last name entered in the /admin/clients provisioning form does NOT propagate to their Clerk user profile (Clerk org invitations don't auto-populate the accepting user's name). So firstName is null. Fix: apply the collected name to the user on provisioning/acceptance, AND fix the fallback copy for genuinely-nameless first visits.

3. Transient blank "Clerk" modal (~2s) during invite acceptance. A blank screen with an empty "Clerk" modal flashes for ~2 seconds during the handoff. Confusing. Soften with a branded loading/interstitial state if possible.

4. "Set up your team" banner appearing white/late. The banner is coded green (TeamSetupBanner.tsx, bg-ladder-green) and the yesterday's flash-prevention gating (server-computed needsTeamSetup, gated on the dashboard fetch) is present in deployed code. Reporter saw it "white." NEEDS REPRO: determine whether it briefly flashes white→green (a pop-in / layout shift as dashboard data loads) vs. stays persistently white (a regression). Capture a screen recording.

Related

• "Complimentary Team" copy for paying clients → Paying Team clients must never see "Complimentary" / comp framing #258
• Post-signup redirect UX → task Add hyperlinks throughout blog posts #8

[ChesterSchendel]

Item 4 ("Set up your team" banner white) — ROOT CAUSE FOUND

Not a flash and not a regression of yesterday's gating fix. It's a CSS cascade-layer bug.

src/app/globals.css lines 45-46:

h1, h2, h3, h4, h5, h6 {
  color: var(--color-foreground);  /* #ffffff */
}

This forces every heading white. It's an unlayered rule, and the project is on Tailwind CSS 4 (utilities live in an @layer). Per CSS cascade-layer precedence, unlayered styles beat layered styles regardless of specificity — so this rule overrides the text-[#1a1a1a] Tailwind utility on the banner's <h3>. The adjacent <p> elements render dark correctly because the rule only targets headings. That's why only the heading is wrong.

Systemic: any heading colored via a Tailwind utility is silently overridden to white app-wide. The banner (dark-on-green) is just where it's visible.

Fix options

• Targeted/now: text-[#1a1a1a]! (important modifier) on the banner heading — forces it past the global rule. One line, low risk.
• Root/correct: move the global heading rule into @layer base { … } so Tailwind utilities win normally. Fixes the whole class of bug but touches every heading — test app-wide. Best done as part of the design-system CSS cleanup (Fix Pro promo copy on dashboard #40).

[ChesterSchendel]

Landing-destination finding (2026-05-29, during the swoop)

Investigated for the bug-fix PR; excluding it because it's not what I first assumed and needs a Clerk re-test:

• layout.tsx already sets signUpFallbackRedirectUrl="/score" and signInFallbackRedirectUrl="/dashboard". Yet the invite-accepting Team Lead landed on home (/) — neither fallback value. So the post-accept destination is not governed by the ClerkProvider fallbacks; it's governed by the org invitation's redirect URL / Clerk Account Portal config.
• The createOrganizationInvitation call in src/app/api/admin/clients/route.ts does not set a redirectUrl. The designer-invite path (/dashboard/team) is a separate code path with its own redirect behavior.
• Proper fix: set the invitation redirectUrl (absolute, from NEXT_PUBLIC_APP_URL) on both the Team Lead provisioning invite and the designer invite, then re-test the accept flow against prod Clerk. Left out of PR Onboarding & admin bug fixes (banner, member count, copy, name, Team Lead terminology) #261 to avoid shipping an unverified auth-redirect change.

Everything else from this issue except the Clerk-handoff flash and this landing item shipped in #261 (welcome copy, name propagation, banner).

[ChesterSchendel]

Clerk bot-challenge interrupts the invite flow (HIGH — 2026-05-29 designer test)

After clicking the invite link, the designer hit a full "clerk.runladder.com — Performing security verification" Cloudflare challenge ("Verifying… you are not a bot") before the (already-rough) blank-screen + Clerk modal. Looks unprofessional and erodes confidence. Intermittent (not seen on the first Team Lead test) — consistent with a reputation/heuristic-based challenge.

CORRECTED diagnosis (initial Cloudflare-DNS hypothesis was wrong): Cloudflare DNS is correct — all five Clerk CNAMEs (accounts, clerk, clk2._domainkey, clk._domainkey, clkmail) are DNS-only (gray cloud). The only proxied records are _domainconnect and pay (both GoDaddy, unrelated). So the challenge is not from runladder's Cloudflare.

Since the Clerk subdomains are DNS-only, traffic goes straight to Clerk's infra, which itself sits behind Cloudflare. The challenge is Clerk's own bot protection (Clerk uses Cloudflare Turnstile for sign-up/sign-in).

Fix direction (Clerk dashboard, NOT Cloudflare):

• Clerk → Configure → Attack Protection → Bot protection / CAPTCHA settings.
• If it's set to a managed/visible challenge, switch to invisible / smart mode so there's no full-page interstitial.
• Re-test the invite flow. Note Turnstile is partly heuristic, so challenges may still appear for suspicious traffic, but the full-page screen shouldn't be the default for normal invited users.

Also (add to onboarding-polish pass): the post-challenge blank screen + bare "Clerk" modal (~2s) compounds the bad first impression.

[ChesterSchendel]

Re-test result (normal browser) — Cloudflare wall does NOT affect real users

Re-ran the invite in a normal (non-incognito) browser, single attempt: no Cloudflare "Performing security verification" screen. Confirms the earlier full-page Turnstile challenge was triggered by test conditions (incognito + many rapid auth attempts from one IP), not something a realistic invited user hits.

Resolution: keep Clerk Bot sign-up protection ON (valuable with free sign-ups / anonymous scoring). The Cloudflare-challenge concern is downgraded — not a demo blocker.

Remaining (low priority): Clerk handoff loading card

Still present: a ~2s card with a spinner ("Secured by clerk") while Clerk verifies the invite ticket (__clerk_status=sign_up&__clerk_ticket=…) and creates the session before redirecting into the app. It's Clerk's own loading state during ticket processing — non-breaking, completes into the app. Options if we polish later: brand/style the loading card via Clerk appearance, or render an app-side branded interstitial on the ticket-handling route. Not a blocker for the demo.

[ChesterSchendel]

Clerk handoff card — Chester's polish asks + feasibility (2026-05-29)

The ~2s loading card is the hosted Clerk Account Portal processing the invite ticket (clerk.runladder.com, __clerk_ticket). Three asks:

1. Hide "Secured by Clerk" name/logo — this is Clerk's "Remove branding", a paid-plan feature (Plan Clerk paid-tier upgrade timing (membership cap + features) #255). Not removable on the free plan via styling. Blocked until upgrade (same upgrade that unlocks custom email templates).
2. Spinner color → Ladder green — the code sets colorPrimary: #6AC89B (layout.tsx), but that only themes components rendered in our app; this card is the hosted portal, which uses the Clerk Dashboard theme (currently default purple). Fix in Clerk Dashboard → Customization → Appearance/Theme → set primary/accent to #6AC89B. Likely free.
3. Show only the spinner — overlaps with Add /organizations page #1; once the branding badge is gone (paid), it's essentially just the spinner.

Thorough alternative: handle invite-acceptance in-app (embedded Clerk component with our appearance) instead of the hosted portal — yields the green spinner, full control of the loading UI, and better control of the post-accept landing destination (overlaps #8). Bigger change; the "do it right" path if these matter enough.

Quick win available now: set the dashboard appearance primary color to Ladder green (#2). The branding removal (#1/#3) waits on the paid upgrade.