A dismissable welcome banner widget for first-time or returning users. Displays an icon, headline, body text, and setup CTAs. Includes a first-session detection callback so consumers can control when it appears. Builds on the visual language of the existing SiteAlert and Callout components.
Introduction
Overview
First-session onboarding banners help users orient themselves and take key setup actions. This widget provides a standardized welcome banner with configurable content, action buttons, and dismiss behavior, along with a callback-based mechanism for detecting first sessions.
Goals
Display a prominent banner with icon, headline, body, and CTA buttons.
Support dismissal with a close button; persist dismissal via consumer callback.
Provide a shouldShow callback for first-session detection.
Visual consistency with SiteAlert and Callout while being distinct as a welcome surface.
Ship Storybook stories for default, multi-CTA, dismissed, and compact states.
Non-Goals
Built-in session tracking or cookie management.
Multi-step wizard flows (use FeatureSpotlight for sequential onboarding).
Analytics tracking (consumer instruments via callbacks).
Scope
In Scope
Item
Description
WelcomeBanner component
Banner with icon, headline, body, CTAs, and dismiss
First-session callback
shouldShow async callback consumer implements
Dismiss behavior
Close button; calls onDismiss for persistence
CTA buttons
Array of action buttons with labels and callbacks
Storybook stories
Default, MultiCTA, Dismissed, Compact, CustomIcon
Out of Scope
Item
Rationale
Session tracking
Consumer owns detection logic
Animated entry
Follow-up enhancement; initial version renders immediately
Progress indicators
Use FeatureSpotlight for step-based onboarding
Users and Pain Points
User
Pain Point
Product teams
No standard first-session banner; teams build ad-hoc solutions
New users
Missing orientation and setup guidance on first visit
Returning users
Seeing welcome content repeatedly when dismissal is not persisted
Definitions
Term
Definition
Welcome banner
A prominent UI surface shown to orient new users
First-session detection
Logic to determine if the current user has not previously seen the banner
CTA
Call-to-action button directing the user toward a setup or onboarding step
Current State
site-alert.tsx provides full-width dismissable alerts with tone variants. callout.tsx provides inline callout blocks. Neither is designed for onboarding welcome flows with multiple CTAs and session-aware visibility. Products build custom welcome sections that lack consistency.
Proposed Solution
Create a WelcomeBanner widget at src/components/widgets/welcome-banner.tsx that:
Renders a visually prominent card with an icon slot, headline, body text, and an array of CTA buttons.
Includes a dismiss/close button that calls onDismiss.
Accepts a shouldShow callback (or simple show boolean) to control visibility.
Uses design-system primitives (Button, Card) and follows SiteAlert/Callout visual patterns.
Supports a compact variant for sidebar or narrow-layout placement.
Requirements
The banner must be controllable via props, not manage its own visibility state internally, and degrade gracefully if shouldShow rejects.
Functional Requirements
ID
Requirement
Priority
FR-01
Render a banner with icon, headline, and body text
Must
FR-02
Display an array of CTA buttons with configurable labels and callbacks
Must
FR-03
Render a dismiss/close button
Must
FR-04
Call onDismiss when dismissed
Must
FR-05
Accept a show boolean prop controlling visibility
Must
FR-06
Support a variant prop with "default" and "compact" options
Should
FR-07
Accept a custom icon via icon prop; default to a waving-hand or sparkle icon
Should
FR-08
Support a tone prop reusing FeedbackTone for color theming
Should
FR-09
Animate out on dismiss using design-system motion tokens
Could
Non-Functional Requirements
ID
Requirement
NFR-01
Bundle size under 2 KB gzipped
NFR-02
Full light/dark theme support
NFR-03
No layout shift on dismiss (height collapses smoothly or element unmounts)
API / Interface Requirements
interface WelcomeBannerAction {
label:string;
onClick:()=>void;
variant?:"default"|"primary"|"ghost";
}
interface WelcomeBannerProps {
show:boolean;
headline:string;
body?:string|ReactNode;
actions?:WelcomeBannerAction[];
icon?:ReactNode;
tone?:FeedbackTone; // default "info"
variant?:"default"|"compact";
onDismiss?:()=>void;
className?:string;
}
Accessibility Requirements
ID
Requirement
A11Y-01
Banner uses role="region" with aria-label="Welcome"
A11Y-02
Dismiss button has aria-label="Dismiss welcome banner"
A11Y-03
CTA buttons are focusable and keyboard-activatable
A11Y-04
When dismissed, focus moves to the next logical element
A11Y-05
Icon is decorative (aria-hidden="true")
Content and Documentation Requirements
Storybook doc page with props, usage patterns, and session-detection guidance.