---
phase: 31
slug: puter.js-zero-config-cloud
status: draft
shadcn_initialized: true
preset: new-york / neutral / cssVariables
created: 2026-04-02
---

# Phase 31 — UI Design Contract

> Visual and interaction contract for Phase 31: Puter.js Zero-Config Cloud.
> Generated by gsd-ui-researcher. Verified by gsd-ui-checker.

---

## Design System

| Property | Value |
|----------|-------|
| Tool | shadcn |
| Preset | new-york, baseColor: neutral, cssVariables: true, style: new-york |
| Component library | Radix UI (via shadcn) |
| Icon library | lucide-react |
| Font | System UI (inherited from body; no custom font declared in index.css) |

Source: `/opt/nexus/ui/components.json` + `/opt/nexus/ui/src/index.css`

---

## Spacing Scale

Declared values (must be multiples of 4):

| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Icon gaps (`gap-1`), inline badge padding |
| sm | 8px | Compact element spacing (`gap-2`), within-form row gaps |
| md | 16px | Default element spacing (`gap-4`), form field gaps |
| lg | 24px | Section padding (`p-6`), card interior padding |
| xl | 32px | Layout gaps (`p-8`) — matches existing wizard card `p-8` |
| 2xl | 48px | Major section breaks — not used in wizard context |
| 3xl | 64px | Page-level spacing — not used in wizard context |

Exceptions:
- Touch targets: `min-height: 44px` enforced globally via `@media (pointer: coarse)` in `index.css` — no per-component override required.
- Provider option cards: `p-4` (16px) interior padding, matching `ModeSelector` card pattern.
- Warning callout (Google OAuth risk): `px-3 py-2` (12px/8px) — compact inline alert pattern matching existing error state style.

Source: existing `NexusOnboardingWizard.tsx` uses `p-8`, `gap-6`, `gap-4`, `gap-2`. ModeSelector uses `p-4`, `gap-3`, `gap-1`.

---

## Typography

| Role | Size | Weight | Line Height |
|------|------|--------|-------------|
| Body | 14px (0.875rem) | 400 | 1.5 |
| Heading | 24px (1.5rem / text-2xl) | 600 | 1.2 |
| Caption / muted | 12px (0.75rem / text-xs) | 400 | 1.4 |

Notes:
- Heading size matches existing wizard `h1` (`text-2xl font-semibold`) — locked by Phase 30 component pattern.
- Label size matches existing form label pattern (`text-sm font-medium`).
- Body size matches existing paragraph + description pattern (`text-sm`).
- Caption is used for step indicator (`text-xs text-muted-foreground`), provider descriptions, and warning footnotes.
- No display-size text (>24px) is needed in this phase — the wizard card is constrained to `max-w-md`.

Source: `NexusOnboardingWizard.tsx` lines 214, 245, 281–283, 294.

---

## Color

All values are shadcn CSS custom properties resolved from `/opt/nexus/ui/src/index.css`.
Both light (Catppuccin Latte) and dark (Catppuccin Mocha) themes are supported.

| Role | Light value | Dark value | Usage |
|------|-------------|------------|-------|
| Dominant (60%) | `--background` (#eff1f5) | `--background` (#1e1e2e) | Wizard backdrop, page background |
| Secondary (30%) | `--card` (#e6e9ef) | `--card` (#181825) | Wizard card surface, provider option cards |
| Accent (10%) | `--primary` (#1e66f5) | `--primary` (#89b4fa) | Selected provider card border + tint, primary CTA button |
| Destructive | `--destructive` (#d20f39) | `--destructive` (#f38ba8) | Google OAuth policy-risk warning text; error state text |

Accent reserved for:
1. The currently selected provider option card border (`border-primary`) and tint (`bg-primary/5`)
2. The primary CTA button ("Continue with Puter", "Continue", "Get Started")
3. The focus ring on interactive inputs and buttons (`--ring`)

Do NOT use accent on: provider logos, status badges, neutral labels, section headings.

Source: `index.css` CSS custom properties; `ModeSelector.tsx` selected-state pattern (`border-primary bg-primary/5`).

---

## Component Inventory

New components introduced in this phase:

| Component | File | Reuses |
|-----------|------|--------|
| `ProviderSelectionStep` | `ui/src/components/onboarding/ProviderSelectionStep.tsx` | `Button`, `cn`, NexusOnboardingWizard card patterns |
| `PuterAuthButton` | `ui/src/components/onboarding/PuterAuthButton.tsx` | `Button` (variant default), lucide `LogIn` icon |
| `GoogleOAuthButton` | `ui/src/components/onboarding/GoogleOAuthButton.tsx` | `Button` (variant outline), lucide `AlertTriangle` icon for warning |
| `ApiKeyEntryForm` | `ui/src/components/onboarding/ApiKeyEntryForm.tsx` | `Input`, `Label`, `Button` |
| `ProviderRiskWarning` | inline in `GoogleOAuthButton` | styled `div` with `text-destructive` + `bg-destructive/10` — matches existing error block |

Existing components consumed without modification:

| Component | Source |
|-----------|--------|
| `Button` | `@/components/ui/button` |
| `Input` | `@/components/ui/input` |
| `Label` | `@/components/ui/label` |
| `Skeleton` | `@/components/ui/skeleton` |
| `NexusOnboardingWizard` | `@/components/NexusOnboardingWizard` — extended with new Step 4 |

---

## Interaction Contract

### Wizard Step Extension

The existing 3-step wizard becomes a 4-step wizard for users without a detected local adapter:

```
Step 1: Hardware Detection  →  Step 2: Mode Selection  →  Step 3: Provider Selection (NEW)  →  Step 4: Root Directory
```

For users with a detected local adapter (hermes_local or claude_local), Step 3 is shown but pre-populated with the detected provider highlighted and a "Continue" shortcut.

Step indicator text: "Step {N} of 4" (updated from current "Step {N} of 3").

### Provider Selection Step Layout

Three option cards in a vertical stack (matching `ModeSelector` grid pattern):

1. **Puter (free, zero-config)** — primary recommendation when no local AI and no API key
   - Card border: `border-primary bg-primary/5` when selected
   - Action: "Continue with Puter" button appears below cards when Puter is selected
   - Auth state: button shows spinner during `puter.auth.signIn()` popup
   - Post-auth state: button label changes to "Puter connected — Continue", icon: `CheckCircle` (lucide), border stays `border-primary`

2. **Google (Gemini free tier)** — shown with risk callout
   - Risk callout: amber/destructive inline alert (see Copywriting section) rendered inside the card when this option is selected — always visible before the "Sign in with Google" button is enabled
   - Action: "Sign in with Google" (disabled until risk callout has been displayed for 3 seconds — anti-accidental-click gate)
   - Post-auth state: "Google connected — Continue"

3. **API Key (subscription providers)** — manual entry
   - When selected: inline form expands below card (no new page) with provider select dropdown + API key input
   - Supported providers listed in dropdown: OpenAI, Anthropic, Groq (extensible)

4. **Skip for now** — ghost button below the three cards, always visible
   - Does not require a selection; proceeds to Step 4 with the probed default adapter

### Loading States

| State | Treatment |
|-------|-----------|
| Puter auth popup in progress | Button disabled, spinner icon (h-4 w-4 animate-spin), label "Connecting to Puter…" |
| Google OAuth in progress | Button disabled, spinner, label "Signing in…" |
| API key saving | Submit button disabled, spinner, label "Saving…" |
| Adapter probe in progress | Provider cards render with `Skeleton` placeholders where pre-detected tool badges would appear; probe is fire-and-forget (cards still interactive) |

### Error States

All errors render inline below the triggering element using the existing error block pattern:
```
<p className="text-sm text-destructive bg-destructive/10 rounded-md px-3 py-2">
  {errorMessage}
</p>
```

### Keyboard and Accessibility

- All provider option cards are `<button type="button">` elements (matching ModeSelector pattern) — keyboard navigable, focus ring via `--ring`.
- Risk warning callout uses `role="alert"` so screen readers announce it immediately when the Google option is selected.
- Auth buttons have `aria-busy="true"` during loading states.
- Skip button has accessible label: "Skip provider setup for now".

---

## Copywriting Contract

| Element | Copy |
|---------|------|
| Step heading (provider step) | "Choose a provider" |
| Step subheading | "No API keys needed for the zero-config path." |
| Primary CTA — Puter | "Continue with Puter" |
| Primary CTA — Google | "Sign in with Google" |
| Primary CTA — API key | "Save API key" |
| Primary CTA — generic Continue | "Continue" |
| Skip action | "Skip for now" |
| Puter card label | "Puter — free, zero-config" |
| Puter card description | "Free AI powered by your Puter.com account. No API key needed." |
| Puter cost attribution note | "Usage is billed to your Puter account, not to Nexus." |
| Google card label | "Google — Gemini free tier" |
| Google card description | "Sign in with Google to access Gemini via your Google account." |
| Google risk warning heading | "Policy risk — read before continuing" |
| Google risk warning body | "Google has suspended accounts that used third-party apps with Gemini credentials. This may affect your Gmail and Workspace access. Use a Google AI Studio API key instead if you want to avoid this risk." |
| Google safe alternative hint | "Safer option: enter a Gemini API key from Google AI Studio below." |
| API key card label | "API key — subscription provider" |
| API key card description | "Use your own OpenAI, Anthropic, or Groq API key." |
| Puter connected success | "Puter connected — Continue" |
| Google connected success | "Google connected — Continue" |
| Empty state (no provider selected, user tries to continue without skipping) | Not applicable — "Skip for now" is always available; no blocking empty state. |
| Error: Puter popup blocked | "Puter sign-in was blocked. Click 'Continue with Puter' directly — do not use keyboard shortcuts." |
| Error: Puter auth failed | "Puter sign-in failed. Check your Puter.com account and try again." |
| Error: Google auth failed | "Google sign-in failed. Try again or use an API key instead." |
| Error: API key save failed | "Could not save API key. Check the key is valid and try again." |
| Error: generic setup failure | "Setup failed. Please try again." |
| Puter auth button loading | "Connecting to Puter…" |
| Google auth button loading | "Signing in…" |
| API key submit loading | "Saving…" |
| Auto-detected tool badge | "{ToolName} detected" (e.g. "Hermes detected", "Claude Code detected") |
| Step indicator | "Step {N} of 4" |

Destructive actions: None in this phase. The Google OAuth risk warning is a caution, not a destructive action confirmation (no data is deleted).

---

## Registry Safety

| Registry | Blocks Used | Safety Gate |
|----------|-------------|-------------|
| shadcn official (ui.shadcn.com) | button, input, label, skeleton, dialog | not required |
| Third-party | none | not applicable |

No third-party shadcn registry blocks are used in this phase. `@heyputer/puter.js` is an npm package loaded via CDN script tag at runtime (not a shadcn registry block) — registry vetting gate does not apply.

---

## Notes for Executor

1. **Wizard step count:** Update the "Step N of 3" indicator to "Step N of 4" in `NexusOnboardingWizard.tsx`. The existing step counter is a plain string — a one-line change.

2. **Puter CDN load:** Load `https://js.puter.com/v2/` dynamically via `loadScript()` helper only when the user clicks "Continue with Puter" — not on wizard open. This avoids loading a large third-party script unnecessarily.

3. **Google risk warning timing gate:** The "Sign in with Google" button must remain disabled for 3 seconds after the Google card is selected to prevent accidental clicks. Use a `useEffect` with a `setTimeout` keyed to the selected card state.

4. **Provider card pre-detection:** Run `agentsApi.probeAdapter()` for `claude_local`, `hermes_local`, and `openclaw_gateway` when the wizard opens (parallel, fire-and-forget). Detected tools surface as a `text-xs text-primary` badge inside the card ("Hermes detected"). Non-detected tools show nothing extra.

5. **Skip-all valid state:** When the user skips Step 3 entirely, the wizard must still complete Step 4 (root directory) and create at least one working agent. The existing `defaultAdapter` probe result handles this — if hermes_local was detected, it's used; otherwise claude_local.

6. **No new shadcn components needed:** All required UI elements are covered by the existing component inventory (button, input, label, skeleton). Do not install additional shadcn components for this phase.

---

## Checker Sign-Off

- [ ] Dimension 1 Copywriting: PASS
- [ ] Dimension 2 Visuals: PASS
- [ ] Dimension 3 Color: PASS
- [ ] Dimension 4 Typography: PASS
- [ ] Dimension 5 Spacing: PASS
- [ ] Dimension 6 Registry Safety: PASS

**Approval:** pending