Skip to content

feat(dashboard): first-visit onboarding overlay#155

Open
nieao wants to merge 1 commit into
Lum1104:mainfrom
nieao:feat/onboarding-overlay
Open

feat(dashboard): first-visit onboarding overlay#155
nieao wants to merge 1 commit into
Lum1104:mainfrom
nieao:feat/onboarding-overlay

Conversation

@nieao
Copy link
Copy Markdown
Contributor

@nieao nieao commented May 17, 2026

TL;DR

Add a 5-step modal that walks new users through the dashboard's core operations
on first visit. Strictly additive: +282 / -0 lines across one new file and a
6-line lazy mount in App.tsx. Auto-hides via localStorage after dismiss;
?onboard=force re-shows it for screenshots and demos.

Motivation

Landing on the dashboard for the first time, a new user sees a node-link graph,
a search box, three view buttons, a layer dropdown, a tour menu, and a handful
of hidden tools (filter / export / path / theme). The visual is striking, but
"what do I click first" isn't obvious — especially on graphs with 50+ nodes
where the entry point matters.

This adds a one-shot teaching moment that names the three views, points at
search + node click, surfaces the layer/tour pair, and lists the hidden tools.

What it teaches (5 steps)

  1. What the graph represents — entities/relations from code or a knowledge wiki
  2. Three view buttons (Overview / Learn / Deep Dive) — each answers a
    different question
  3. Search + node click — find by name, click for the details panel
  4. Layer switch + Project Tour — drill into one category, or follow a
    guided walkthrough
  5. Hidden features (Filter / Export / Path / Theme) and Shift+? for
    keyboard shortcuts

Design

  • Lazy-loaded via Suspense, mirroring the existing KeyboardShortcutsHelp
    and PathFinderModal mount pattern — ships in its own chunk, no impact on
    initial bundle size for users who've dismissed it.
  • Inline styles, no new CSS file — easier to land alongside the existing
    structure without touching the global stylesheet.
  • Architectural-minimalism dark palette consistent with the existing
    dashboard: off-black surface, warm accent (#c8a882), Noto Serif SC
    headings, generous whitespace.
  • localStorage key ua-onboarding-dismissed-v1 — versioned so future
    content changes can re-trigger when needed.
  • Accessible: keyboard-navigable buttons, click-outside to close (without
    remembering dismiss), explicit "不再显示 / Skip" affordance.

Tested on

Windows 11 + Chrome via Playwright CDP. All 5 steps render, the progress bar
tracks, prev / next / dismiss / finish all behave correctly, localStorage
persists dismiss across reloads, ?onboard=force re-shows for testing.

Compatibility

  • No new dependencies — uses React 19 hooks already present.
  • No changes to data flow, store, schema, or other components — strictly
    additive. If OnboardingOverlay is removed, nothing else breaks.
  • First-visit only by default, then permanently dismissed — no impact on
    returning users.

🤖 Generated with Claude Code

Add a 5-step modal that walks new users through the dashboard's core operations
on first visit. Auto-hides via localStorage after dismiss; can be force-shown
with `?onboard=force` for screenshots and demos.

## What it teaches

1. What the graph represents (entities/relations from code or wiki)
2. Three view buttons (Overview / Learn / Deep Dive) — each answers a different
   question
3. Search + node click — find by name, click for details panel
4. Layer switch + Project Tour — drill into a category, or follow a guided
   walkthrough
5. Hidden features (Filter / Export / Path / Theme) and Shift+? for keyboard
   shortcuts

## Design

- Inline styles, no extra CSS file — easier to land in the existing structure
- Lazy-loaded via Suspense like the other modals (KeyboardShortcutsHelp,
  PathFinderModal) so it ships in a separate chunk
- Architectural-minimalism dark palette consistent with the existing dashboard:
  off-black surface, warm accent (#c8a882), Noto Serif SC headings, generous
  whitespace
- localStorage key `ua-onboarding-dismissed-v1` — versioned so future content
  changes can re-trigger
- Accessible: keyboard-navigable buttons, click-outside to close (without
  remembering dismiss), explicit "不再显示" / "Skip" affordance

## Tested

- Windows 11 + Chrome via Playwright: 5 steps render, progress bar tracks,
  prev/next/dismiss/finish all work, localStorage persists dismiss across
  reloads, `?onboard=force` re-shows for testing
- No new dependencies (uses React 19 hooks already present)
- No changes to data flow, store, or other components — strictly additive

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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