waggle-os/docs/redesign-warm-hive/pr7-recon/03-screen-auth-design.md

PR7 Recon · Screen 13 — Auth (Clerk, themed) · DESIGN spec

RECON ONLY. No product code touched. Every claim cites file:line. Scope: faithful component-level breakdown of the Auth screen design so a build agent can implement it against the warm token system, PLUS the REAL-vs-BUILD reality of auth in this monorepo (which is the load-bearing surprise here).

Sources read in full:

• docs/design_handoff_waggle_app/design-files/screens/auth.html (181 lines)
• docs/design_handoff_waggle_app/SCREENS.md §13 (lines 269-278)
• docs/design_handoff_waggle_app/design-files/styles/waggle.css (155 lines, token grounding)
• docs/redesign-warm-hive/BUILD-PLAN.md §6 (PR7 row) + §7.5 (the BYO/metered gate)
• Codebase auth reality: packages/server/src/plugins/auth.ts, …/local/security-middleware.ts, …/services/user-service.ts, apps/web/src/components/os/AppShell.tsx, apps/web/src/lib/adapter.ts, apps/www/app/sign-in/[[...sign-in]]/page.tsx, apps/www/app/api/stripe/checkout/route.ts

---

0. The headline (read this before building)

The desktop app (apps/web) — PR7's build target — has NO authenticated user identity and NO Clerk React SDK today. Auth screen 13 is therefore overwhelmingly EXTERNAL-DEP + decision-gated, not a re-skin of something already wired.

Two distinct server modes coexist; the design's "Clerk" assumption only matches ONE of them, and it's NOT the one the desktop talks to:

Mode	Auth mechanism	Has a real user account?	Where the design's screen would live
Local sidecar (what the Tauri desktop / apps/web talks to)	per-process machine bearer token via GET /api/auth/session-token, exchanged so loopback callers can't drive the API. NOT a login. (packages/server/src/local/security-middleware.ts:235-377, :238)	No. "Identity" is the local IdentityLayer name the user types in onboarding (adapter.getIdentity() → /api/identity, IdentityResponse.name), a memory record, not an account. (apps/web/src/lib/adapter.ts:1090-1095; tauri-bindings.ts:133-145)	n/a today — there is no /auth route in apps/web (grep for '/auth'/appId.*auth → No matches)
Cloud / Team server (packages/server/src/index.ts + plugins/auth.ts)	real Clerk — verifyToken(), clerkClient.users.getUser(), Drizzle users table, auto-provision on first auth (packages/server/src/plugins/auth.ts:3,19-52; services/user-service.ts:30-58)	Yes (Clerk user → internal UUID)	n/a in apps/web either
apps/www (Next.js landing)	real Clerk UI, hosted <SignIn/>/<SignUp/> catch-all pages, themed via <ClerkProvider> (apps/www/app/sign-in/[[...sign-in]]/page.tsx:1,17-23); @clerk/nextjs@^7.3.0 + @clerk/themes@^2.4.57 (apps/www/package.json:15-16)	Yes	This is the only place Clerk's themeable React UI already exists.

So the build decision PR7 must surface: does screen 13 ship as a real auth flow in the desktop at all, or is desktop auth always optional/local and "sign in for sync" links out to the apps/www Clerk flow? The design copy itself ("account is optional — Waggle runs fully local without one") leans toward the latter. See §6 Decisions.

---

1. Exact layout (split: brand-panel left + form right)

From auth.html:

• Top control bar (.controls, auth.html:78-87) — concept-harness chrome: a label Auth · Clerk · state (:79), a 4-way segmented state switcher Sign in / Sign up / Verify / SSO (:80-85), and a theme toggle button (:86). This bar is concept scaffolding for previewing states — NOT product UI. In the real build the "state" is route/Clerk-flow-driven, not a manual segmented control.
• Split grid (.split, :89; CSS :20) — grid-template-columns: 1.05fr 1fr (brand panel slightly wider than the form).
• Left brand panel (.brandside, :90-101; CSS :22-33):
  • 56px padding, linear-gradient(160deg, var(--bg-2), var(--bg)), right border --line-soft, full-bleed honeycomb texture .comb masked by a radial gradient at 30%/30% (CSS :23).
  • Three vertical zones via justify-content:space-between: brand lockup (hex "W" mark + "Waggle" wordmark, :92), pitch (h2 + p, :93-96), trust lines (:97-100).
  • Hidden below 820px — @media (max-width:820px){ .brandside{display:none} } (CSS :73). Mobile = form only.
• Right form panel (.formside, :103-152; CSS :36-37): centered, max-width:380px card, scrollable. Holds the four state views (.view, only one .on at a time, CSS :72).

---

2. Every state — verbatim copy + behavior

2a. Sign in (data-view="signin", auth.html:106-117) — default

• Heading "Welcome back"; sub "New to Waggle? Create an account" (link → signup) (:107).
• SSO block (.sso, :108-111): two buttons — "Continue with Google" (mono "G" badge) and "Continue with Apple" (mono "⌥" badge).
• Divider "or" (.divider, :112).
• Email field, demo value mara@egzakta.com (:113).
• Password field with a lrow header: label + "Forgot?" link (→ verify view in the demo; in product → Clerk reset) (:114).
• Primary "Sign in" button (data-go="home" → routes to Home) (:115).
• Fineprint: "By continuing you agree to the Terms & Privacy Policy." (:116).

2b. Sign up (data-view="signup", :120-132) — carries the local-first note

• Heading "Create your hive"; sub "Already have an account? Sign in" (:121).
• .localnote honey banner (:122; CSS :67-70) — THE load-bearing trust copy:

  "You don't need this to start." Waggle works locally right away — create an account only when you want sync or a team.

• SSO block: single "Sign up with Google" (:124).
• Divider "or" (:126).
• Fields: Name (demo Mara Kovač), Email (placeholder you@company.com), Password (placeholder "At least 10 characters") (:127-129).
• Primary "Create account" (→ verify) (:130).
• Fineprint: "We'll send a code to verify your email." (:131).

Password rule "At least 10 characters" (:129) is design copy. Real minimum is Clerk-policy-driven — do NOT hardcode "10" in validation; mirror whatever the Clerk instance enforces, or omit the count.

2c. Verify — 6-box OTP (data-view="verify", :135-140)

• Heading "Check your email"; sub "We sent a 6-digit code to mara@egzakta.com" (the email is bolded in --text-2) (:136).
• .otp row of 6 single-char inputs (:137; CSS :60-64): 48×56px, mono 22px, maxlength=1, inputmode="numeric"; a .filled class flips border + text to honey on a non-empty box.
• Auto-advance / backspace nav (the explicit design requirement), in the demo script (:163-169): input event focuses the next box when filled; keydown Backspace on an empty box focuses the previous box. The demo pre-fills boxes 0-2 with [2,4,9].
• Primary "Verify & continue" (→ Home) (:138).
• "Didn't get it? Resend code · Use a different email" (→ back to sign in) (:139).

2d. SSO / enterprise (data-view="sso", :143-150)

• Heading "Single sign-on"; sub "Use your organization's identity provider." (:144).
• Field "Work email or organization" (placeholder you@company.com) (:145).
• Primary "Continue with SSO" (:146).
• Divider "enterprise" (:147).
• Muted .localnote (neutral, not honey — background:var(--bg-2)) (:148), verbatim:

  SAML, SCIM provisioning, and audit logs are available on Teams and KVARK. Talk to sales →

• Back link "← Back to sign in" (:149).

2e. Brand-panel pitch + trust copy (verbatim, :93-100)

• h2: "Your work follows you, everywhere." ("everywhere." in honey via em, CSS :29).
• p: "Sign in to sync your hive across devices, collaborate with a team, and pick up any project exactly where you left off — on any machine."
• Trust line 1 (shield icon): "An account is optional — Waggle runs fully local without one"
• Trust line 2 (arrow icon): "Your memory stays yours; sign-in only adds sync"

---

3. Warm tokens + primitives used (for faithful build)

All from waggle.css (dark :9-61, light :63-101). The auth HTML uses these named tokens directly:

Primitive	Tokens (from auth.html <style> + waggle.css)
Brand-panel bg	linear-gradient(160deg, --bg-2, --bg); border --line-soft (auth.html:22)
Honeycomb texture	.comb data-URI honey @ 5% stroke, radial mask (CSS :119-122)
Hex mark	.hex clip-path (waggle.css:117) + linear-gradient(150deg,--honey-bright,--honey-deep) + --honey-glow (auth.html:25)
SSO buttons	--surface bg, --line-strong border; hover → --honey-line + --surface-2 (auth.html:44-45)
Divider	flex rule, --line-soft lines, mono --text-dim label (auth.html:47-48)
Inputs	--surface bg, --line border, --r:11px; focus → --honey-line + --honey-glow (auth.html:52-53)
OTP boxes	mono, --r:12px; .filled → --honey-line + honey text (auth.html:62-64)
Primary submit	--honey bg, text #1a1407; hover → --honey-bright (auth.html:56-57)
Honey trust banner	.localnote → --honey-wash bg + --honey-line border (auth.html:68)
Neutral enterprise banner	.localnote overridden to --bg-2 + --line-soft (auth.html:148)
Links / accents	--honey; fineprint --text-dim (auth.html:41,55,58)
Focus ring (global)	:focus-visible{outline:2px solid --honey} (waggle.css:125)
Fonts	--sans Hanken Grotesk, --mono JetBrains Mono (waggle.css:51-53)

In the real build these map to the PR1-landed warm tokens in apps/web (BUILD-PLAN.md §3.1, already shipped per MEMORY.md — index.css carries the verbatim waggle.css names + the shadcn HSL recolor). So no new tokens are needed — the build re-skins Clerk/custom components against the already-present token set. Honey "#1a1407" button-foreground is the same --primary-foreground PR1 set (BUILD-PLAN.md:67).

#1a1407 (honey-button text) and data-theme theming are app-global; the screen inherits dark default + the warm-paper light variant for free.

---

4. Clerk's themeable components vs custom

Per SCREENS.md §13: "Build with Clerk components themed to the tokens." Mapping the design's pieces to what Clerk's appearance API covers:

Design piece	Clerk coverage	Notes
Sign in (Google/Apple SSO + email/pw)	<SignIn/>	Social buttons, email/pw, "Forgot?" reset are first-class. Theme via appearance.variables (colorPrimary ← --honey, colorBackground ← --surface, etc.) + elements overrides. @clerk/themes already a www dep (apps/www/package.json:16).
Sign up + local-first note	<SignUp/> + custom	The form is Clerk; the honey .localnote "you don't need this to start" banner is custom chrome placed above/around <SignUp/>.
Verify 6-box OTP (auto-advance/backspace)	Clerk built-in	Clerk's email-code step renders its own OTP input with auto-advance. Re-skinning to the exact 48×56 honey boxes needs elements.otpCodeField* overrides (or Clerk Elements / a fully custom flow if pixel-parity is required).
SSO / enterprise (SAML/SCIM → Teams/KVARK)	partial Clerk + custom	Clerk Enterprise SSO exists but is a paid Clerk feature + per-org config. The design's panel is mostly a custom "Talk to sales" CTA (KVARK funnel), not a live SAML form. Safe build: custom panel, link to sales.
Left brand panel + pitch + trust lines	fully custom	Pure layout chrome around the Clerk <SignIn/>/<SignUp/> card.

To match the warm design, two integration styles are possible:

1. Themed Clerk prebuilt (<SignIn appearance={…}/>) wrapped in the custom split layout — fastest, matches SCREENS.md's instruction, but OTP/element pixel-parity is limited to what appearance.elements exposes.
2. Clerk Elements / headless (useSignIn, useSignUp) feeding the design's exact custom inputs/OTP/buttons — full visual control, more code, the only way to get the exact 48×56 honey OTP boxes + custom SSO buttons.

The brand panel, dividers, local-first banner, and enterprise→sales CTA are custom in either case.

---

5. Honesty contract — where Auth could fabricate (MUST be gated off)

Auth is the single highest-risk screen for fabrication because the desktop has no real account. Each of these must be real or absent — never invented:

1. A logged-in identity that isn't real. The demo hardcodes mara@egzakta.com / Mara Kovač (auth.html:113,127,136). A build MUST NOT pre-fill or display a fake signed-in user. The desktop's only "identity" is the local IdentityLayer name (adapter.getIdentity(), apps/web/src/lib/adapter.ts:1090), which is not an authenticated account and must never be rendered as "signed in".
2. Fake SSO success. Google/Apple/SSO buttons that "succeed" without a real Clerk (or any) provider configured are fabrication. If Clerk isn't wired in the desktop, these buttons must be honestly disabled / "coming soon" / route to apps/www, not fake a session. (No Clerk publishable key path exists in apps/web today.)
3. Fake OTP verification. The demo's "Verify & continue" advances on any input (auth.html:138,164). Real verify must check a real code via Clerk; otherwise the verify state must not claim to have verified anything.
4. "Continue → Home" as a real auth boundary. In the demo all submits just navigate to Home (auth.html:171-172). The desktop already has a real structural auth gate (the session-token ensureReady() contract, adapter.authgate.test.ts) — but that gates the local sidecar, not a user login. The Auth screen must not imply a login happened when only the local app opened.
5. SAML/SCIM as live. The enterprise panel names SAML/SCIM/audit logs (auth.html:148). These are Teams/KVARK/Clerk-Enterprise features — the panel is a sales CTA, and must stay one unless those are genuinely provisioned. Do not render a SAML form that does nothing.

Gate-off rule: if Clerk is not configured for the desktop, the entire authenticated path (SSO, email/pw, OTP, SSO/org) should degrade to the honest local-first framing the design itself already provides ("an account is optional — Waggle runs fully local") and a single "Sign in for sync →" link to the real flow, rather than a non-functional look-alike.

---

6. Decisions a build agent must get answered first

1. Does desktop auth ship at all, or link out?

   • Options: (a) full Clerk in apps/web (add @clerk/clerk-react + publishable key + a /auth route — none exist today); (b) desktop stays local-only, "Sign in for sync" deep-links to the existing apps/www Clerk flow (apps/www/app/sign-in/...); (c) embed/redirect to apps/www in a webview.
   • Recommendation: (b) for first ship — matches "account is optional", reuses the real, already-themed apps/www Clerk surface, and avoids standing up a second Clerk React integration + token bridge into the local sidecar (which currently authenticates with a machine token, not a user token).
   • Blast radius: large if (a) — new dep, new route, new token-exchange between Clerk user-JWT and the local bearer; small if (b)/(c).

2. BYO-key vs Waggle-metered (DESIGN_POV §4 / BUILD-PLAN §7.5 #5). Explicitly flagged as blocking Billing/PR7 (DESIGN_POV.md:62-70, :88-90; BUILD-PLAN.md:165-166). It reshapes whether "sign in" is even required to use models (BYO = local key, no account needed; metered = account + payment up front). Settle before building 13/14.

   • Blast radius: shapes Auth (is sign-in required for inference?), Onboarding model gate, Billing, Usage. Founder decision, not a build choice.

3. OTP fidelity: themed Clerk prebuilt vs Clerk Elements/headless. Pixel-exact 48×56 honey OTP boxes need headless; "good enough" needs only appearance overrides.

   • Recommendation: themed prebuilt first (ships SCREENS.md's instruction), upgrade to Elements only if review demands the exact boxes. Blast radius: small/local.

4. SSO/enterprise panel = sales CTA only (no live SAML). Recommendation: keep it a custom "Talk to sales → KVARK/Teams" panel; do not implement live SAML in PR7. Blast radius: small.

---

7. REAL vs DERIVABLE vs MUST-BUILD vs EXTERNAL-DEP (screen 13)

Feature	Status	Evidence / note
Warm tokens + primitives the screen needs	REAL	PR1 landed verbatim waggle.css tokens in apps/web (BUILD-PLAN.md §3.1, MEMORY.md PR1). No new tokens.
Split brand panel, pitch, trust lines, dividers, local-first banner, enterprise CTA	MUST-BUILD (custom chrome, low risk)	Pure layout/copy; no backend. All copy verbatim in §2/§4 above.
Clerk <SignIn/>/<SignUp/>/OTP UI in apps/web	EXTERNAL-DEP	No @clerk/clerk-react in apps/web; no publishable key; no /auth route (grep: no matches). Clerk React UI exists ONLY in apps/www (apps/www/app/sign-in/[[...sign-in]]/page.tsx).
Real user account / login / session	EXTERNAL-DEP	Real Clerk auth lives in cloud/team server (packages/server/src/plugins/auth.ts:3,31-48) + users table (services/user-service.ts). Desktop sidecar auth is a machine bearer token, not a user (local/security-middleware.ts:235-377).
Local "identity" (name) for the user row	REAL but NOT an account	adapter.getIdentity() → /api/identity → IdentityLayer name (adapter.ts:1090; tauri-bindings.ts:133-145); used in AppShell.tsx:98-108, degrades to "Account". Must NOT be shown as "signed in".
SSO with Google/Apple	EXTERNAL-DEP	Clerk social providers; need Clerk + OAuth app config. Not wired in desktop.
SAML / SCIM (enterprise)	EXTERNAL-DEP (Teams/KVARK/Clerk-Enterprise)	Design panel is a sales CTA, not a live form (auth.html:148).
"Continue → Home" navigation	DERIVABLE	Routes to /home; desktop already has the structural sidecar auth gate (adapter.authgate.test.ts) but that is not a user login.
Theme toggle / segmented state switcher (top bar)	N/A — concept scaffolding	.controls is harness chrome for previewing states (auth.html:78-87), not product UI.

---

8. One-paragraph build brief (for the implementer)

Build screen 13 as a custom warm split layout (left brand panel: hex "W" + honeycomb .comb + verbatim pitch/trust copy from §2e; right: a centered max-width:380px card) in apps/web, against the already-present PR1 warm tokens (no new tokens). The form itself is EXTERNAL-DEP on Clerk, which is wired only in apps/www today — so the first, honest ship is local-first: the desktop stays usable without an account (reuse the design's own "you don't need this to start" .localnote), and a single "Sign in for sync →" links to the real, already-themed apps/www Clerk flow rather than a non-functional Clerk look-alike in the desktop. If founder confirms full in-app Clerk (decision §6.1a), add @clerk/clerk-react + a publishable key + a /auth route + a user-JWT→local-sidecar token bridge, and theme <SignIn/>/<SignUp/>/OTP via appearance (Elements only if pixel-exact OTP boxes are required). Never render a fabricated signed-in identity, fake SSO/OTP success, or a dead SAML form (§5). The BYO-vs-metered decision (§6.2) blocks this screen and Billing and must be settled first.