UI Components Guide

Master every element of the Astronox interface.

Overview

Astronox's interface is designed for efficiency and clarity. This guide explains every component and how to use it effectively.

Main Layout

┌──────────────────────────────────────────────────────────────┐
│  ≡  Astronox            [📋 Plan Hub] [📎] [⚙️ Settings]    │  ← Top Bar
├──────────┬───────────────────────────────────────────────────┤
│          │                                                   │
│  [🔍]    │  💬 Welcome! How can I help you today?            │
│          │                                                   │
│ [+ New]  │  👤 Show me my recent documents                   │
│          │                                                   │
│ ┌──────┐ │  💬 Found 23 documents in your home folder.       │
│ │Chat 1│ │     Here are the 10 most recent:                  │  ← Main Chat Area
│ └──────┘ │                                                   │
│  Chat 2  │     📄 Report.pdf - Dec 20                        │
│  Chat 3  │     📄 Notes.txt - Dec 19                         │
│          │     ...                                           │
│  Sidebar │                                                   │
├──────────┼───────────────────────────────────────────────────┤
│          │  Type your message...               [Send] [📎]  │  ← Input Area
└──────────┴───────────────────────────────────────────────────┘

1. Top Navigation Bar

Left Section

≡ Menu Button (Hamburger Icon)

• Purpose: Toggle sidebar visibility
• Use: Hide sidebar for more chat space on smaller screens
• Shortcut: Cmd/Ctrl + B

Astronox Logo/Title

• Purpose: Branding and app identification
• Click action: Currently decorative (no action)

Right Section

📋 Plan Hub Button

• Purpose: Open the multi-step planning panel
• When visible: Appears when AI creates a multi-step plan
• Badge: Shows number of active/pending steps
• Click action: Opens Plan Hub overlay (see section below)

📎 Attach Button

• Purpose: Add files/images to your message
• Supported types: Images (JPG, PNG, GIF), PDFs, text files
• Size limit: 8MB per conversation total
• Click action: Opens file picker
• Note: Currently under repair (known issue)

⚙️ Settings Button

• Purpose: Access all configuration options
• Click action: Opens Settings panel (see section below)
• Shortcut: Cmd/Ctrl + ,

2. Left Sidebar

Search Bar

┌─────────────────┐
│  🔍  Search...  │
└─────────────────┘

Features:

• Filter conversations by content
• Search across all message history
• Real-time results as you type
• Case-insensitive

Tips:

• Search by date: "yesterday", "last week"
• Search by topic: "python", "backup script"
• Search by file names mentioned in chats

New Chat Button

┌───────────────────────┐
│  + New Conversation   │
└───────────────────────┘

Actions:

• Click: Create new conversation immediately
• Shortcut: Cmd/Ctrl + N
• Auto-switches to the new chat

Conversation List

Each conversation shows:

┌─────────────────────────┐
│ 💬 Chat Title            │  ← Auto-generated from first message
│    Last message preview  │  ← Snippet of most recent message
│    2 hours ago          │  ← Relative timestamp
└─────────────────────────┘

Interaction:

• Click: Switch to that conversation
• Hover: Shows full title (if truncated)
• Active chat: Highlighted with different background
• Right-click: Context menu (coming soon: delete, rename)

Organization:

• Sorted by most recent activity
• Pinned chats stay at top (future feature)
• Virtualized scrolling for performance (handles 1000+ chats)

3. Main Chat Area

Message Display

User Messages (Your messages)

┌──────────────────────────────────────┐
│  👤 You                    2:30 PM   │
│  Show files in Downloads folder      │
└──────────────────────────────────────┘

Styling:

• Right-aligned on some themes
• User avatar/icon
• Timestamp on hover
• Your attached images appear inline

AI Messages (Astronox responses)

┌──────────────────────────────────────┐
│  🤖 Astronox              2:30 PM   │
│                                      │
│  Found 47 files in Downloads:       │
│                                      │
│  📄 document.pdf      2.4 MB         │
│  🖼️ screenshot.png    800 KB        │
│  ...                                 │
└──────────────────────────────────────┘

Features:

• Markdown rendering (bold, italic, code blocks, lists)
• Syntax highlighting for code
• Clickable links
• Expandable sections for long outputs

System Messages

┌──────────────────────────────────────┐
│  ℹ️ System                           │
│  Conversation started Dec 20, 2025   │
└──────────────────────────────────────┘

When shown:

• Conversation creation
• Settings changes during chat
• Connection issues or errors

Special Message Types

Tool Usage Indicators

🛠️ Using tool: list_directory
📂 Reading: /Users/you/Downloads
✅ Found 47 items

Purpose: Shows what Astronox is doing in real-time

Types:

• 🛠️ Tool started
• 📂 File operation
• 💾 Writing data
• 🔍 Searching
• ✅ Success
• ❌ Error

Confirmation Prompts (Safe Mode)

┌──────────────────────────────────────────────┐
│  ⚠️ Confirmation Required                    │
│                                              │
│  About to delete 15 files:                   │
│  • old-file-1.txt                            │
│  • old-file-2.pdf                            │
│  ...                                         │
│                                              │
│  This action cannot be undone.               │
│                                              │
│  [ ✓ Proceed ]  [ ✗ Cancel ]               │
└──────────────────────────────────────────────┘

Risk Levels:

• 🟡 Medium: File modifications, moves
• 🟠 High: File deletions, system changes
• 🔴 Very High: Bulk deletions, critical system operations

Actions:

• Proceed: Execute the operation
• Cancel: Abort and explain cancellation
• Confirmation expires after 5 minutes of inactivity

Thinking Animation

🤖 Astronox is thinking...
   ●●●○○

When shown:

• Waiting for AI response
• Processing long requests
• Streaming not yet started

Types:

• Pulsing dots animation
• Shows AI is working, not frozen

Error Messages

┌──────────────────────────────────────┐
│  ❌ Error                            │
│                                      │
│  Operation failed: Permission denied │
│  Error code: FS_403                  │
│                                      │
│  Try granting file access in         │
│  System Preferences → Privacy        │
└──────────────────────────────────────┘

Components:

• Clear error description
• Error code (for troubleshooting)
• Suggested fix (when available)
• Link to docs (for common issues)

Message Actions

Hover over any message to see:

• Copy button (📋): Copy message text
• Retry (🔄, user messages only): Resend your message
• Save as Automation (💾, AI responses): Save script/code

4. Message Input Area

┌────────────────────────────────────────────────────────┐
│  Type your message...                     [Send] [📎]  │
│                                                        │
│  [Shift+Enter for new line]                           │
└────────────────────────────────────────────────────────┘

Text Input Field

Features:

• Multi-line support (auto-expands up to 10 lines)
• Markdown preview (coming soon)
• Drag-and-drop files to attach
• Paste images directly from clipboard

Keyboard Shortcuts:

• Enter: Send message
• Shift + Enter: New line (don't send)
• Cmd/Ctrl + V: Paste (text or image)
• Cmd/Ctrl + A: Select all
• Esc: Clear input

Send Button

States:

• Enabled: When text is entered (blue/teal)
• Disabled: When input is empty (gray)
• Loading: During message send (spinner)

Click action: Send message to AI

Attach Button (📎)

Purpose: Add files to your message

Supported:

• Images: JPG, PNG, GIF, WebP
• Documents: PDF, TXT, MD
• Max total per conversation: 8MB

Flow:

1. Click paperclip
2. Select file(s) from picker
3. Preview appears below input
4. Send message (files included automatically)

Attachment Preview:

┌─────────────────────────────────────┐
│  📎 Attachments (2)                 │
│                                     │
│  🖼️ screenshot.png    800 KB   [✕] │
│  📄 document.pdf      2.4 MB   [✕] │
└─────────────────────────────────────┘

• Click [✕] to remove before sending
• Hover to see full filename

5. Plan Hub Panel

┌─────────────────────────────────────────────────┐
│  📋 Current Plan                          [✕]  │
├─────────────────────────────────────────────────┤
│                                                 │
│  ✅ 1. Find files older than 30 days           │
│     Found 47 files                              │
│                                                 │
│  ⏳ 2. Group files by type                     │
│     In progress...                              │
│                                                 │
│  ⏸️ 3. Move to Archive folder                  │
│     Waiting...                                  │
│                                                 │
│  ⏸️ 4. Generate summary report                 │
│     Queued                                      │
├─────────────────────────────────────────────────┤
│  Progress: 1/4 steps complete (25%)            │
└─────────────────────────────────────────────────┘

When It Appears

• AI detects multi-step task in your request
• AI calls set_plan tool to create visual roadmap
• Badge appears on Plan Hub button

Step States

⏸️ Queued (Gray)

• Not started yet
• Waiting for previous steps

⏳ In Progress (Blue, animated)

• Currently executing
• May show sub-progress

✅ Complete (Green)

• Successfully finished
• Shows result summary

❌ Failed (Red)

• Encountered error
• Shows error message
• Can retry or skip

⏭️ Skipped (Yellow)

• User chose to skip
• Or auto-skipped due to dependency failure

Interactions

Click on step:

• Expand to see details
• View logs/output
• Retry if failed

Panel Actions:

• Pause: Halt execution (before confirmations)
• Resume: Continue paused plan
• Cancel: Stop all remaining steps
• Close [✕]: Hide panel (plan continues in background)

Use Cases

Perfect for:

• File organization workflows
• Project setup sequences
• Batch processing tasks
• System maintenance routines
• Multi-stage data processing

6. Settings Panel

┌─────────────────────────────────────────────────┐
│  ⚙️ Settings                              [✕]  │
├─────────────────────────────────────────────────┤
│                                                 │
│  [General] [API Keys] [Advanced] [About]       │
│                                                 │
│  General Settings                               │
│  ─────────────────                              │
│                                                 │
│  Access Mode                                    │
│  ● Safe Mode  ○ Full Mode                      │
│                                                 │
│  Theme                                          │
│  [Dark ▼]                                      │
│                                                 │
│  ...                                            │
│                                                 │
├─────────────────────────────────────────────────┤
│               [Cancel]  [Save Settings]        │
└─────────────────────────────────────────────────┘

Opening Settings

• Click ⚙️ icon in top-right
• Shortcut: Cmd/Ctrl + ,
• From chat: Ask "Open settings"

Tabs

General Tab

• Access Mode (Safe/Full)
• Theme selection
• Language/region
• Startup preferences

API Keys Tab

• Provider selection (Gemini/MintAI)
• API key input fields
• Connection testing
• Usage stats (future)

Advanced Tab

• Memory management
• Clipboard history settings
• Process guard options
• Debug/logging

About Tab

• App version
• Update checking
• License information
• Links to documentation

Settings Controls

Toggle Switches:

Enable Memory  [ON/OFF toggle]

• Click to toggle
• Blue = enabled, gray = disabled

Radio Buttons:

Access Mode:
● Safe Mode
○ Full Mode

• Select one option
• Current selection filled

Dropdowns:

Model Selection  [Gemini 2.5 Flash ▼]

• Click to expand options
• Select from list

Text Inputs:

API Key: [••••••••••••••••] [Show]

• Click [Show] to reveal
• Paste key or type

Buttons:

• Test Connection: Verify API key
• Clear Data: Delete conversations
• Reset Defaults: Restore factory settings

Saving Changes

• Save Settings: Applies and closes panel
• Cancel: Discards changes and closes
• Auto-save: Some settings apply immediately

7. Status Indicators

Top-Right Corner

🟢 Connected     ← Green: Ready
🟡 Processing    ← Yellow: Working
🔴 Error         ← Red: Problem
⚪ Disconnected  ← Gray: Offline

Connection Status

🟢 Connected (Green)

• API key valid
• Network available
• Ready for requests

🟡 Processing (Yellow)

• Handling your request
• Tool execution in progress
• Plan step running

🔴 Error (Red)

• API error (key invalid, rate limit)
• Network issue
• Service unavailable

⚪ Disconnected (Gray)

• No internet connection
• App starting up
• API unreachable

Click status: Shows detailed info tooltip

8. Context Menus (Right-Click)

In Conversation List

┌──────────────────┐
│ Open             │
│ Rename           │  ← Coming soon
│ Delete           │  ← Coming soon
│ Pin to Top       │  ← Coming soon
└──────────────────┘

In Message

┌──────────────────┐
│ Copy Text        │
│ Copy as Code     │
│ Save as File     │
│ Retry (user msg) │
└──────────────────┘

9. Keyboard Navigation

Global Shortcuts

In Chat

In Message

10. Responsive Behavior

Window Resizing

• Narrow (<800px): Sidebar auto-hides, hamburger menu appears
• Medium (800-1200px): Sidebar visible, compact chat area
• Wide (>1200px): Full layout, optimal spacing

Zoom Levels

• Cmd/Ctrl + +: Zoom in (125%, 150%)
• Cmd/Ctrl + -: Zoom out (75%, 50%)
• Cmd/Ctrl + 0: Reset zoom (100%)

11. Visual Feedback

Loading States

• Skeleton screens while loading conversations
• Pulsing animation during AI thinking
• Progress bars for file operations
• Spinners for quick actions

Animations

• Smooth transitions between chats
• Slide-in panels for settings/plan hub
• Fade effects for messages appearing
• Bounce effect on errors

Color Coding

• Teal/Blue: Primary actions, links
• Green: Success, completed
• Yellow: Warnings, in-progress
• Red: Errors, dangerous actions
• Gray: Disabled, inactive

12. Accessibility

Screen Reader Support

• All buttons have ARIA labels
• Message roles properly marked
• Keyboard navigation fully supported

High Contrast Mode

• Available in settings (future)
• System theme detection

Keyboard-Only Navigation

• Tab through all interactive elements
• Enter to activate buttons
• Arrow keys in lists

Tips for Efficient UI Use

✅ Pin Important Chats

• Keep frequently used conversations at the top (coming soon)
• Use search to find older chats quickly

✅ Use Keyboard Shortcuts

• Learn Cmd+N for new chat, Cmd+K for search
• Speed up workflow significantly

✅ Watch Plan Hub

• Monitor multi-step tasks visually
• Catch errors early in sequences

✅ Enable Safe Mode While Learning

• See confirmations before actions
• Understand what Astronox is doing
• Switch to Full Mode when confident

✅ Organize with Multiple Chats

• Create separate chats for different projects
• Keeps context focused and relevant
• Easier to find past conversations

Next: Explore Sample Prompts to see these UI components in action.