igny8/docs/PRE-LAUNCH/ITEM-4-PAGE-FLOW-UX.md

Item 4: Page Flow and Workflow UX Improvements

Priority: High
Target: Production Launch
Last Updated: December 11, 2025

---

Overview

Improve overall navigation, page structure, workflow clarity, and helper systems across all main user-facing areas including Setup, Workflow (Planner/Writer), Account, and Settings. This encompasses page flow standardization, helper notifications, tooltips, metrics panels, and notification systems.

---

Current Implementation Analysis

Main Menu Groups

Location: frontend/src/layout/AppLayout.tsx and navigation components

Current Groups:

1. Setup - Sites, Sectors, Integrations setup
2. Workflow - Planner (Keywords, Clusters, Ideas) and Writer (Tasks, Content, Images)
3. Account - Billing, Team, Profile
4. Settings - System settings, prompts, preferences

Issues:

• Inconsistent page header patterns across groups
• Some pages missing breadcrumbs or context
• Linear workflows (Planner → Writer) not clearly guided
• Cross-navigation between related pages unclear

---

Page Header Component

Location: frontend/src/components/common/PageHeader.tsx

Current Features:

• Page title
• Last updated timestamp
• Site/Sector selector (can be hidden)
• Optional refresh button
• Optional badge
• Optional navigation tabs

Strengths: ✅ Standardized across modules
✅ Site/sector context management
✅ Auto-loads sectors when site changes

Missing: ❌ No breadcrumbs for deeper navigation
❌ No contextual help link
❌ No step indicators for workflows
❌ No quick action buttons section

---

Module Navigation Tabs

Location: frontend/src/components/navigation/ModuleNavigationTabs.tsx

Current Usage:

• Planner pages: Keywords | Clusters | Ideas | Mapping
• Writer pages: Tasks | Content | Images

Strengths: ✅ Consistent tab design
✅ Active tab highlighting
✅ Responsive layout

Missing: ❌ No tab progress indicators
❌ No disabled state for incomplete prerequisites
❌ No tooltips explaining each tab

---

Helper Systems

Current State:

• No systematic helper notifications
• No onboarding tooltips
• No inline guidance text
• No contextual help system

What's Needed:

• Welcome messages for first-time page visits
• Tooltips for icons and complex actions
• Inline help text under form fields
• Step-by-step workflow banners
• Contextual "Learn more" links

---

Metrics Display

Current Locations:

• Dashboard: Overview metrics
• Individual pages: Table counts, filters
• Footer: Module-specific metrics (some pages only)

Component: frontend/src/components/dashboard/ModuleMetricsFooter.tsx

Issues:

• Inconsistent placement (some pages have footer metrics, some don't)
• No collapsible panel option
• Metrics not updated in real-time
• No metric explanations (tooltips)

---

Required Improvements

A. Standardize Page Structure

Universal Page Template

All workflow pages should follow this structure:

<div className="page-container">
  {/* 1. Page Header */}
  <PageHeader 
    title="Page Title"
    badge={badge}
    navigation={<ModuleNavigationTabs tabs={tabs} />}
  />
  
  {/* 2. Step Banner (if workflow page) */}
  {isWorkflowPage && <StepBanner currentStep={2} totalSteps={5} />}
  
  {/* 3. Helper Notification (first visit or contextual) */}
  {showHelper && <HelperNotification message="..." />}
  
  {/* 4. Page Actions Bar */}
  <PageActionsBar 
    primaryAction={primaryAction}
    secondaryActions={secondaryActions}
    filters={filters}
  />
  
  {/* 5. Main Content */}
  <MainContent>
    {/* Tables, forms, cards, etc. */}
  </MainContent>
  
  {/* 6. Bottom Metrics Panel (collapsible) */}
  <MetricsPanel metrics={metrics} collapsible={true} />
</div>

---

B. New Components to Create

1. StepBanner Component

File: frontend/src/components/workflow/StepBanner.tsx (NEW)

Purpose: Show current step in multi-step workflows

Props:

interface StepBannerProps {
  currentStep: number;
  totalSteps: number;
  steps: Array<{
    label: string;
    href: string;
    completed: boolean;
  }>;
  onStepClick?: (stepIndex: number) => void;
}

UI Design:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2 of 5: Organize into Clusters

1. Extract Keywords ✓ → 2. Cluster Keywords ● → 3. Generate Ideas → 4. Create Content → 5. Publish
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

States:

• ✓ Completed (green, clickable)
• ● Current (blue, active)
• Pending (gray, disabled or clickable)

Usage:

<StepBanner 
  currentStep={2}
  totalSteps={5}
  steps={[
    { label: 'Extract Keywords', href: '/planner/keywords', completed: true },
    { label: 'Cluster Keywords', href: '/planner/clusters', completed: false },
    { label: 'Generate Ideas', href: '/planner/ideas', completed: false },
    { label: 'Create Content', href: '/writer/tasks', completed: false },
    { label: 'Publish', href: '/writer/content', completed: false },
  ]}
/>

---

2. HelperNotification Component

File: frontend/src/components/helper/HelperNotification.tsx (NEW)

Purpose: Display contextual guidance and tips

Types:

• Welcome: First-time page visit
• Info: General information
• Tip: Best practice suggestion
• Warning: Potential issue
• Success: Achievement/milestone

Props:

interface HelperNotificationProps {
  type: 'welcome' | 'info' | 'tip' | 'warning' | 'success';
  title: string;
  message: string;
  actions?: Array<{
    label: string;
    href?: string;
    onClick?: () => void;
  }>;
  dismissible?: boolean;
  onDismiss?: () => void;
}

UI Design:

┌─────────────────────────────────────────────────┐
│ 💡 Welcome to Keywords                          │
│                                                 │
│ This is where you extract and manage SEO        │
│ keywords. Start by adding keywords manually or  │
│ importing from a CSV file.                      │
│                                                 │
│ [Import CSV] [Learn More] [Got it] [×]         │
└─────────────────────────────────────────────────┘

Persistence:

• Store dismissed state in localStorage per page
• Key: helper_dismissed_{page_slug}
• Option to show "Show hints again" in settings

---

3. Tooltip Component Enhancement

File: frontend/src/components/ui/Tooltip.tsx (enhance existing)

Add:

• Keyboard accessibility (ESC to close, tab navigation)
• Delay before show (300ms hover)
• Max width constraints
• Arrow positioning
• Rich content support (not just text)

Usage Examples:

{/* Simple text tooltip */}
<Tooltip content="Click to cluster all keywords">
  <button>Cluster</button>
</Tooltip>

{/* Rich content tooltip */}
<Tooltip content={
  <div>
    <strong>Clustering</strong>
    <p>Groups keywords by semantic similarity</p>
    <a href="/help/clustering">Learn more →</a>
  </div>
}>
  <InfoIcon />
</Tooltip>

---

4. InlineGuidance Component

File: frontend/src/components/helper/InlineGuidance.tsx (NEW)

Purpose: Small help text under form fields

Props:

interface InlineGuidanceProps {
  text: string;
  type?: 'info' | 'warning' | 'error';
  icon?: ReactNode;
}

UI Design:

[Input Field: Enter keyword]
ℹ️ Use lowercase, no special characters. Separate multiple keywords with commas.

Usage:

<FormField label="Keywords">
  <input type="text" placeholder="Enter keyword" />
  <InlineGuidance 
    text="Use lowercase, no special characters. Separate multiple keywords with commas."
  />
</FormField>

---

5. Enhanced MetricsPanel Component

File: frontend/src/components/dashboard/ModuleMetricsPanel.tsx (NEW)

Improvements over current MetricsFooter:

• Collapsible/expandable
• Fixed to bottom or inline at page bottom
• Real-time updates
• Tooltips explaining each metric
• Click to filter/drill-down
• Export metrics option

Props:

interface MetricsPanelProps {
  title: string;
  metrics: Array<{
    label: string;
    value: string | number;
    subtitle?: string;
    icon?: ReactNode;
    color?: string;
    tooltip?: string;
    onClick?: () => void;
  }>;
  collapsible?: boolean;
  defaultCollapsed?: boolean;
  position?: 'fixed' | 'relative';
}

UI Design (Expanded):

┌─────────────────────────────────────────────────────────┐
│ ▼ Keyword Metrics                          [Collapse] × │
├─────────────────────────────────────────────────────────┤
│ Total: 450   │ New: 120   │ Mapped: 330   │ Vol: 125K  │
│ ℹ️ All saved │ ℹ️ Unmapped │ ℹ️ In cluster │ ℹ️ Search  │
│              │             │               │   volume   │
└─────────────────────────────────────────────────────────┘

UI Design (Collapsed):

▶ Keyword Metrics: 450 total, 120 new, 330 mapped

---

C. Navigation Improvements

1. Add Breadcrumbs

Component: frontend/src/components/navigation/Breadcrumbs.tsx (NEW)

Usage:

<Breadcrumbs 
  items={[
    { label: 'Setup', href: '/setup' },
    { label: 'Sites', href: '/setup/sites' },
    { label: 'Site Settings' }, // Current page (no href)
  ]}
/>

Display:

Home > Setup > Sites > Site Settings

Rules:

• Show for pages 3+ levels deep
• Current page not clickable
• Auto-hide on mobile if > 3 items

---

2. Cross-Navigation Links

Add "Next Step" buttons between related pages:

Examples:

Current Page	Next Step Button	Action
Keywords	"Cluster Keywords →"	Navigate to Clusters page
Clusters	"Generate Ideas →"	Navigate to Ideas page
Ideas	"Create Tasks →"	Convert ideas to tasks, navigate to Tasks
Tasks	"Generate Content →"	Trigger content generation
Content	"Generate Images →"	Navigate to Images page

Implementation:

<PageActionsBar
  primaryAction={{
    label: 'Cluster Keywords',
    icon: <ArrowRightIcon />,
    onClick: () => navigate('/planner/clusters'),
    variant: 'primary'
  }}
/>

---

3. Workflow Progress Indicator (Global)

Location: Header or sidebar

Display current workflow stage:

Planner Workflow: Step 2/3
├─ Keywords ✓
├─ Clusters ● (in progress)
└─ Ideas

Writer Workflow: Not started

Click to navigate to any completed or current step

---

D. Settings Reorganization

Current Problems

• Settings scattered across multiple locations
• Inconsistent categories
• Hard to find specific settings

Proposed Structure

New Layout: frontend/src/pages/Settings/

Settings/
├── index.tsx (Settings hub with cards)
├── General.tsx
├── Publishing.tsx
├── Pagination.tsx
├── Branding.tsx
├── WorkflowDefaults.tsx
├── Integrations.tsx
├── Notifications.tsx
├── Account.tsx
└── Billing.tsx (redirect to /billing)

Settings Categories:

Category	Subcategories	What It Contains
General	Account basics	Display name, timezone, language, date format
Publishing	WordPress settings	Connection, publishing defaults, SEO rules, auto-publish options
Pagination	List controls	Items per page for each module (keywords, clusters, ideas, etc.)
Branding	Appearance	Logo, colors, custom CSS (if applicable)
Workflow Defaults	AI settings	Default word count, tone, structure, author profile
Integrations	External services	API keys, OAuth connections, webhooks
Notifications	Alert preferences	Email alerts, in-app notifications, notification types
Account & Billing	Subscription	Plan details, usage, credits, invoices, team members

Settings Hub (Landing Page):

<SettingsHub>
  <SettingsCard 
    icon={<GeneralIcon />}
    title="General"
    description="Basic account settings and preferences"
    href="/settings/general"
  />
  <SettingsCard 
    icon={<PublishIcon />}
    title="Publishing"
    description="WordPress connection and publishing rules"
    href="/settings/publishing"
  />
  {/* ... more cards */}
</SettingsHub>

---

E. Notification System

Notification Types

Type	Use Case	Display	Action
Progress	Task started, queued, processing	Blue info icon	View progress modal
Success	Task completed, export success	Green check icon	View result
Failure	API error, validation failed	Red error icon	View error details, retry
Action Required	Missing settings, incomplete setup	Orange warning icon	Navigate to fix

Notification Dropdown

Location: Header, bell icon with badge count

Features:

• List notifications chronologically
• Read/unread states
• Mark all as read
• Filter by type
• Clear all button
• Links to relevant pages

Example Notification:

┌─────────────────────────────────────────────┐
│ 🔵 Content Generation Started               │
│ "Best SEO Tools 2024" - 2 minutes ago      │
│ [View Progress]                             │
├─────────────────────────────────────────────┤
│ ✅ Clustering Completed                      │
│ 45 keywords → 8 clusters - 10 min ago      │
│ [View Clusters]                             │
├─────────────────────────────────────────────┤
│ ❌ Image Generation Failed                   │
│ Insufficient credits - 1 hour ago          │
│ [Purchase Credits] [Dismiss]               │
└─────────────────────────────────────────────┘

Implementation

Backend:

• Create Notification model with account FK
• API endpoints: list, mark read, clear
• Emit notifications on key events

Frontend:

• useNotifications() hook
• NotificationDropdown component
• Auto-refresh every 30 seconds
• WebSocket support (future enhancement)

---

F. Header Metrics Enhancement

Current: Basic stats in dashboard

Improved: Always-visible header metrics

Location: Right side of header (next to user menu)

Display:

[Icon] 3 In Progress  |  [Icon] 5 Completed  |  [Icon] 2,450 Credits  |  [Bell] 7

Click to expand:

• In Progress: Show list of running tasks
• Completed: Recent completions
• Credits: Usage breakdown, purchase link
• Bell: Notification dropdown

---

Page-Specific Improvements

Planner Pages

Keywords Page

Add:

• ✅ Helper: "Import keywords or add manually to start"
• ✅ Tooltip on "Cluster" button: "Group keywords by semantic similarity"
• ✅ Inline guidance on import: "CSV format: keyword, volume, difficulty"
• ✅ Next step button: "Cluster Keywords →"
• ✅ Metrics panel: Total, New, Mapped, Avg Volume

Clusters Page

Add:

• ✅ Helper: "Clusters organize keywords into topic groups"
• ✅ Step banner: Step 2/3 in Planner workflow
• ✅ Tooltip on cluster cards: Show keyword count, volume
• ✅ Next step: "Generate Ideas →"
• ✅ Metrics panel: Clusters, Avg size, Total volume

Ideas Page

Add:

• ✅ Helper: "Content ideas are generated from your clusters"
• ✅ Step banner: Step 3/3 in Planner workflow
• ✅ Content structure badge with tooltip
• ✅ Next step: "Create Tasks →" (converts to tasks)
• ✅ Metrics panel: Ideas, Cluster hubs, Word count estimates

---

Writer Pages

Tasks Page

Add:

• ✅ Helper: "Tasks are content generation jobs queued for AI"
• ✅ Step banner: Step 1/3 in Writer workflow
• ✅ Status badges with tooltips
• ✅ Next step: "Generate Content →"
• ✅ Metrics panel: Total tasks, Queued, Completed, Total words

Content Page

Add:

• ✅ Helper: "Review and edit AI-generated content before publishing"
• ✅ Step banner: Step 2/3 in Writer workflow
• ✅ Status badges (draft/review/published)
• ✅ Next step: "Generate Images →"
• ✅ Metrics panel: Total content, Drafts, Published, Total words

Images Page

Add:

• ✅ Helper: "Generate images for your content from AI prompts"
• ✅ Step banner: Step 3/3 in Writer workflow
• ✅ Image preview on hover
• ✅ Next step: "Publish to WordPress →"
• ✅ Metrics panel: Total images, Generated, Published

---

Automation Page

Add:

• ✅ Helper: "Automation runs the entire workflow automatically"
• ✅ Stage progress cards with clear metrics
• ✅ Pause/Resume/Cancel controls
• ✅ Real-time stage updates
• ✅ Estimated completion time
• ✅ Credit consumption display

---

Implementation Plan

Phase 1: New Components (Week 1)

1. ✅ Create StepBanner component
2. ✅ Create HelperNotification component
3. ✅ Enhance Tooltip component
4. ✅ Create InlineGuidance component
5. ✅ Create MetricsPanel component

Phase 2: Navigation (Week 1-2)

1. ✅ Create Breadcrumbs component
2. ✅ Add cross-navigation buttons
3. ✅ Implement workflow progress indicator
4. ✅ Update ModuleNavigationTabs with tooltips

Phase 3: Settings Reorganization (Week 2)

1. ✅ Create new Settings pages structure
2. ✅ Migrate existing settings
3. ✅ Create Settings hub landing page
4. ✅ Add category cards

Phase 4: Notification System (Week 2-3)

1. ✅ Create Notification model (backend)
2. ✅ Create notification endpoints
3. ✅ Create NotificationDropdown component
4. ✅ Integrate with existing workflows
5. ✅ Add bell icon with badge to header

Phase 5: Page Updates (Week 3)

1. ✅ Update all Planner pages with new components
2. ✅ Update all Writer pages with new components
3. ✅ Update Automation page
4. ✅ Add helpers, tooltips, metrics to each page

---

Success Metrics

• ✅ All workflow pages have step banners
• ✅ All pages have helper notifications on first visit
• ✅ All icons and actions have tooltips
• ✅ All form fields have inline guidance
• ✅ Settings are organized and easy to find
• ✅ Users receive notifications for all key events
• ✅ Cross-navigation reduces clicks to complete workflows
• ✅ Metrics panels show real-time data
• ✅ User feedback indicates clearer navigation

---

Related Files Reference

Components (NEW)

• frontend/src/components/workflow/StepBanner.tsx
• frontend/src/components/helper/HelperNotification.tsx
• frontend/src/components/helper/InlineGuidance.tsx
• frontend/src/components/navigation/Breadcrumbs.tsx
• frontend/src/components/dashboard/MetricsPanel.tsx
• frontend/src/components/notifications/NotificationDropdown.tsx

Components (Enhance)

• frontend/src/components/common/PageHeader.tsx
• frontend/src/components/navigation/ModuleNavigationTabs.tsx
• frontend/src/components/ui/Tooltip.tsx

Pages (Update)

• All frontend/src/pages/Planner/*.tsx
• All frontend/src/pages/Writer/*.tsx
• frontend/src/pages/Automation/*.tsx
• frontend/src/pages/Settings/*.tsx (reorganize)

Backend (NEW)

• backend/igny8_core/modules/system/models.py - Add Notification model
• backend/igny8_core/modules/system/views.py - Notification endpoints

---

Notes

• Helper notifications should be non-intrusive and dismissible
• Tooltips should be brief (2-3 sentences max)
• Metrics should update in real-time or near-real-time
• Settings should be searchable (future enhancement)
• Consider onboarding tour for new users (future phase)
• All guidance text should be editable by admin (future enhancement)