portabase/docs/superpowers/specs/2026-06-17-onboarding-channel-config-style.md

Onboarding Channel Config + Style Refactor

Date: 2026-06-17
Branch: poc/onboarding-setup
Scope: Two concerns:

1. Notifier/storage steps gain a real two-phase configuration flow (fake data, stored in flowData)
2. All onboarding step cards, toggles, and inputs adopt the org-combobox design language

---

1. Configuration Flow — Notifier & Storage Steps

Goal

When a user clicks a provider in the notifier or storage step, they should be able to configure it (Slack webhook URL, S3 credentials, etc.) before it is added to their list. Data is stored in flowData only — no server actions are called during onboarding.

Phase Machine

Each step manages a local phase:

type Phase =
  | { kind: "grid" }
  | { kind: "configuring"; provider: string }

Phase "grid"

• Shows the provider selection grid (style: see Section 2)
• Already-configured providers show at top with check badge and remove button
• Unconfigured providers are clickable → transition to configuring
• "Continue" button visible if at least 0 channels configured (step is optional)
• "Add another" link/button visible when at least 1 configured

Phase "configuring"

• Header: provider icon + name + "Back" button (returns to grid, no save)
• Channel name Input (required, min 5 chars per existing schema)
• renderChannelForm(provider, form) renders the provider-specific fields
• useZodForm with NotificationChannelFormSchema (notifier) or StorageChannelFormSchema (storage)
• Submit validates → appends { id: crypto.randomUUID(), provider, label, name, config } to local channels list → returns to grid phase
• No server action called

Updated OnboardingChannel type

export type OnboardingChannel = {
    id: string;
    provider: string;
    label: string;
    name: string;
    config: Record<string, unknown>;
};

step-defaults.tsx reads id and label from notifiers/storages — unchanged, continues to work.

Files

• src/features/onboarding/onboarding.types.ts — extend OnboardingChannel
• src/features/onboarding/steps/step-notifier.tsx — full rewrite
• src/features/onboarding/steps/step-storage.tsx — full rewrite

Dependencies reused

• renderChannelForm from @/features/channel/channels-helpers
• NotificationChannelFormSchema / StorageChannelFormSchema from @/features/channel/channel-form.schema
• useZodForm, Form, FormField, FormItem, FormLabel, FormControl, FormMessage from @/components/ui/form
• notificationProviders / storageProviders from their respective helpers

---

2. Style Refactor — All Onboarding Steps

Goal

Replace hardcoded dark colors and inconsistent <button> styling across all step components with design-system tokens matching the org-combobox visual language.

Design Tokens

Toggle/selection cards (provider cards, theme buttons, DB toggles, SSO buttons, security method buttons):

State	Classes
Inactive	border border-border rounded-lg hover:bg-accent/50 hover:border-primary/20 transition-colors
Active	border border-primary/20 bg-primary/10 text-primary rounded-lg

Icon container (inside provider cards):

size-9 rounded-md border bg-muted/50 shadow-sm flex items-center justify-center

Check badge (selected state on provider cards):

size-5 rounded-full bg-primary flex items-center justify-center ml-auto
  → Check className="size-3 text-primary-foreground" strokeWidth={3}

Inputs (Input, Textarea): already shadcn — remove any hardcoded color overrides. No component change.

Navigation buttons (Button shadcn variants default/outline/ghost): unchanged, already correct.

Shell (onboarding-shell.tsx): bg-zinc-950/bg-zinc-900 intentionally kept dark — not changed.

Files Affected

File	Change
step-sso-gate.tsx	SSO provider buttons → toggle card style
step-security.tsx	Passkey/2FA method buttons → toggle card style
step-preferences.tsx	Theme toggle buttons → toggle card style
step-project-create.tsx	DB toggle buttons → toggle card style
step-notifier.tsx	Provider cards → toggle card style (done as part of config flow rewrite)
step-storage.tsx	Provider cards → toggle card style (done as part of config flow rewrite)
step-invite-members.tsx	Audit for hardcoded colors, clean if needed
step-agent-create.tsx	Audit for hardcoded colors, clean if needed

---

3. Conditional Step Graph — Skip Agent Steps When No Agents

Rule

If the user skips or submits agent-create with zero agents (flowData.agents empty or undefined), skip agent-waiting, project-create, and db-settings — jump directly to finish.

Step Graph Change

onboarding-steps.tsx — agent-create entry:

{
    id: "agent-create",
    component: StepAgentCreate,
    isSkippable: true,
    nextStep: (ctx) => {
        const agents = ctx.flowData?.agents as unknown[] | undefined;
        return agents && agents.length > 0 ? "agent-waiting" : "finish";
    },
}

All other steps unchanged.

Rationale

• agent-waiting pings the agent — no agent to ping
• project-create groups databases under an agent project — no agent, no project
• db-settings configures agent DB retention — no project selected, empty state anyway

Files

• src/features/onboarding/onboarding-steps.tsx — update agent-create.nextStep

---

Out of Scope

• Server actions / real DB persistence during onboarding (fake data only)
• step-account-info.tsx, step-org-create.tsx, step-defaults.tsx, step-agent-waiting.tsx, step-finish.tsx — no toggle cards, no hardcoded colors
• onboarding-shell.tsx background colors — intentionally dark
• Any changes outside src/features/onboarding/

---

Acceptance Criteria

1. Clicking a provider in notifier/storage step → shows config form with correct provider-specific fields
2. Submit config form → validates with existing schema → provider appears in grid with check badge and remove button
3. Continue → saves all configured channels (with name + config) to flowData.notifiers / flowData.storages
4. All toggle cards across steps use design-system tokens (no border-white/10, no hardcoded bg)
5. step-defaults.tsx selects still work (reads id + label from channels)
6. pnpm exec tsc --noEmit — no new errors in onboarding files
7. Skip agent-create with 0 agents → jumps to finish (agent-waiting, project-create, db-settings not shown)
8. Create agents → normal flow through agent-waiting → project-create → db-settings → finish