Hosted ongabo.esvia theHypermedia Protocol

Enhancement Note: Removing Templates from the onboardingwhat should we do now instead?

I'm working on removing the templates step from the onboarding on desktop, and now when the user finishes the complete flow we send them to their beautiful empty site.

This is not ideal IMHO, so I prepare this options to do instead:

Option 1: Empty State Component (Recommended - Simple & Clean)

Show a helpful empty state when the home document has no content:

// In the document view component
{document.isEmpty && (
  <EmptyHomeState>
    <WelcomeCard>
      <h2>Welcome to your new site! 🎉</h2>
      <p>Here's what you can do next:</p>
      
      <ActionCard onClick={startEditing}>
        <Icon>✏️</Icon>
        <Title>Start writing</Title>
        <Description>Click anywhere to begin editing your home page</Description>
      </ActionCard>
      
      <ActionCard onClick={copyProfileLink}>
        <Icon>🔗</Icon>
        <Title>Share your profile</Title>
        <Description>Copy your profile link to share with others</Description>
      </ActionCard>
      
      <ActionCard onClick={openPublishDialog}>
        <Icon>🚀</Icon>
        <Title>Publish your site</Title>
        <Description>Make your site accessible on the web</Description>
      </ActionCard>
    </WelcomeCard>
  </EmptyHomeState>
)}

Pros: Non-intrusive, disappears once they add content, clean design

Cons: Easy to miss if they don't look carefully

Option 2: First-Run Tour/Spotlight

Use a lightweight tour library to highlight key UI elements:

// After onboarding completes
if (isFirstVisit) {
  startTour([
    { element: '#editor', message: 'Click here to start writing' },
    { element: '#share-button', message: 'Share your profile with this link' },
    { element: '#publish-button', message: 'Publish your site when ready' },
  ])
}

Pros: Interactive, guides attention to actual UI elements

Cons: Can feel intrusive, requires tour library

Option 3: Persistent Checklist (GitHub-style)

Add a dismissible checklist that stays visible until completed:

<OnboardingChecklist>
  <ChecklistItem completed={hasEditedDocument}>
    ✏️ Edit your home document
  </ChecklistItem>
  <ChecklistItem completed={hasSharedProfile}>
    🔗 Share your profile link
  </ChecklistItem>
  <ChecklistItem completed={hasPublishedSite}>
    🚀 Publish your first site
  </ChecklistItem>
</OnboardingChecklist>

Pros: Clear progress tracking, can be dismissed

Cons: Takes up screen space, adds complexity

Option 4: Pre-populated Starter Content

Add a starter template directly in the home document:

# Welcome to your site! 👋

You can edit this page by clicking anywhere. Here's what you can do:

- **Edit this page**: Just click and start typing
- **Share your profile**: [Copy link](#)
- **Publish your site**: Make it live on the web

Delete this text and start creating!

Pros: Immediate context, shows editing works, can include examples

Cons: User has to delete it, might feel cluttered

Option 5: Contextual Tooltips

Show tooltips that appear on specific UI elements on first visit:

<Tooltip 
  open={isFirstVisit && !hasClickedEditor}
  content="Click anywhere to start editing your home page"
>
  <Editor />
</Tooltip>

Pros: Minimal, contextual, progressive disclosure

Cons: Might be too subtle, hard to orchestrate timing

What I prefer

Use Option 1 (Empty State) as the primary approach, with:

  1. Empty state card when document is empty showing the 3 actions

  2. Make actions immediately functional:

    • "Start writing" → Focus editor and show cursor

    • "Share profile" → Copy link + show toast

    • "Publish site" → Open publish dialog

  3. Once they add any content, the empty state disappears forever

  4. Optional: Add a small "?" help button in the sidebar or titlebar that shows these tips again

Do you like what you are reading?. Subscribe to receive updates.

Unsubscribe anytime