Skip to content

Add first-run welcome overlay for new users#28

Open
lucaslosantos wants to merge 1 commit intopablodelucca:mainfrom
lucaslosantos:feat/welcome-overlay
Open

Add first-run welcome overlay for new users#28
lucaslosantos wants to merge 1 commit intopablodelucca:mainfrom
lucaslosantos:feat/welcome-overlay

Conversation

@lucaslosantos
Copy link

@lucaslosantos lucaslosantos commented Feb 24, 2026

What

Adds a WelcomeOverlay component that appears over the empty office when no agents exist yet. It walks new users through the three steps required to get started — install Claude Code, sign in, then click + Agent — without leaving the panel.

The overlay disappears automatically as soon as the first agent is created, so it has no impact on regular use.

Why

Without this, opening the panel for the first time shows an empty office with no indication of what to do next. The only affordance is the + Agent button, but clicking it does nothing useful if Claude Code isn't installed. This makes the first experience confusing, especially for people who aren't already familiar with Claude Code - which is one of the main gains of this extension.

Changes

File Change
webview-ui/src/components/WelcomeOverlay.tsx New component — three-step setup guide with one-click copy for the install command
webview-ui/src/constants.ts CLAUDE_CODE_INSTALL_CMD added per project constant conventions
webview-ui/src/App.tsx Import + render <WelcomeOverlay /> when agents.length === 0 && !isEditMode

Design decisions

  • Pointer events: the outer wrapper is pointerEvents: none so the office canvas, zoom controls, and bottom toolbar remain fully interactive behind the card.
  • Auto-dismiss: no close/dismiss button. The overlay is a loading state, not a modal — it goes away the moment its condition is no longer true (agent created). No state to manage, no way for it to get stuck.
  • Pixel art aesthetic: sharp corners, 2px solid border, hard offset shadow, --pixel-* CSS variables — matches all other overlays in the project.
  • Constant in constants.ts: the install URL is centralised so it's easy to update if the URL ever changes, consistent with project rules.

How to test

  1. Run npm run build and press F5 to open the Extension Development Host
  2. Open the Pixel Agents panel in the bottom bar
  3. Before any agents exist: the welcome card should appear centred over the office with the three setup steps and a working Copy button
  4. Click + Agent: the overlay disappears immediately as the character spawns
  5. Close all agents: the overlay returns
  6. Switch to Layout edit mode: the overlay is hidden (edit mode has its own context)
  7. Switch back out of edit mode with no agents: overlay reappears

Screenshots

The overlay as seen on first open (no agents):
Captura de pantalla 2026-02-24 a las 22 37 26

Note: the office canvas and all controls remain visible and interactive behind the card.

Shows a centered card over the empty office when no agents exist yet,
guiding new users through the three steps needed to get started:
install Claude Code, sign in, then click + Agent.

The overlay disappears naturally as soon as the first agent is created,
so it does not interfere with normal use.

Changes:
- `WelcomeOverlay.tsx` — new component (components/ pattern)
- `constants.ts` — CLAUDE_CODE_INSTALL_CMD extracted per project rules
- `App.tsx` — render overlay when agents.length === 0 and not in edit mode

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@lucaslosantos
Copy link
Author

@pablodelucca let me know if you would like me to modify it in any way. excited to contribute to such a cool project

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant