Redflag/docs/3_BACKLOG/2025-12-17_Toggle_Button_UI_UX_Considerations.md

Toggle Button UI/UX Considerations - December 2025

Status: ⚠️ PLANNED / UNDER DISCUSSION

Problem Statement

The current ON/OFF vs AUTO/MANUAL toggle buttons in AgentHealth component have visual design issues that affect usability and clarity.

Location: aggregator-web/src/components/AgentHealth.tsx lines 358-387

Current Implementation Issues

1. Visual Confusion Between Controls

• ON/OFF and AUTO/MANUAL use similar gray colors when off
• Hard to distinguish states at a glance
• No visual hierarchy between primary (ON/OFF) and secondary (AUTO/MANUAL) controls

2. Disabled State Ambiguity

• When subsystem is OFF, AUTO/MANUAL shows cursor-not-allowed and gray styling
• Gray disabled state looks too similar to enabled MANUAL state
• Users may not understand why AUTO/MANUAL is disabled

3. No Visual Relationship

• Doesn't communicate that AUTO/MANUAL depends on ON/OFF state
• Controls appear as equals rather than parent/child relationship

Current Code

// ON/OFF Toggle (lines 358-371)
<button className={cn(
  'px-3 py-1 rounded text-xs font-medium transition-colors',
  subsystem.enabled
    ? 'bg-green-100 text-green-700 hover:bg-green-200'
    : 'bg-gray-100 text-gray-600 hover:bg-gray-200'
)}>
  {subsystem.enabled ? 'ON' : 'OFF'}
</button>

// AUTO/MANUAL Toggle (lines 374-388)
<button className={cn(
  'px-3 py-1 rounded text-xs font-medium transition-colors',
  !subsystem.enabled ? 'bg-gray-50 text-gray-400 cursor-not-allowed' :
  subsystem.auto_run
    ? 'bg-blue-100 text-blue-700 hover:bg-blue-200'
    : 'bg-gray-100 text-gray-600 hover:bg-gray-200'
)}>
  {subsystem.auto_run ? 'AUTO' : 'MANUAL'}
</button>

Proposed Solutions (ETHOS-Compliant)

Option 1: Visual Hierarchy & Grouping

Make ON/OFF more prominent and visually group AUTO/MANUAL as subordinate.

Benefits:

• Clear primary vs secondary control relationship
• Better visual flow
• Maintains current functionality

Implementation:

// ON/OFF - Larger, more prominent
<button className="px-4 py-2 text-sm font-medium rounded-lg transition-colors
  {subsystem.enabled ? 'bg-green-600 text-white hover:bg-green-700' : 'bg-gray-300 text-gray-700 hover:bg-gray-400'}">
  {subsystem.enabled ? 'ENABLED' : 'DISABLED'}
</button>

// AUTO/MANUAL - Indented or bordered subgroup
<div className={!subsystem.enabled ? 'opacity-50' : ''}>
  <button className="px-3 py-1 text-xs rounded transition-colors
    {subsystem.auto_run ? 'bg-blue-600 text-white' : 'bg-gray-200 text-gray-700'}">
    {subsystem.auto_run ? 'AUTO' : 'MANUAL'}
  </button>
</div>

Option 2: Lucide Icon Integration

Use existing Lucide icons (no emoji) for instant state recognition.

Benefits:

• Icons provide immediate visual feedback
• Consistent with existing icon usage in component
• Better for color-blind users

Implementation:

import { Power, Clock, User } from 'lucide-react'

// ON/OFF with Power icon
<Power className={subsystem.enabled ? 'text-green-600' : 'text-gray-400'} />
<span>{subsystem.enabled ? 'ON' : 'OFF'}</span>

// AUTO/MANUAL with Clock/User icons  
{subsystem.auto_run ? (
  <><Clock className="text-blue-600" /><span>AUTO</span></>
) : (
  <><User className="text-gray-600" /><span>MANUAL</span></>
)}

Option 3: Simplified Single Toggle

Remove AUTO/MANUAL entirely. ON means "enabled with auto-run", OFF means "disabled".

Benefits:

• Maximum simplicity
• Reduced user confusion
• Fewer clicks to manage

Drawbacks:

• Loses ability to enable subsystem but run manually
• May not fit all use cases

Implementation:

// Single toggle - ON runs automatically, OFF is disabled
<button className={cn(
  'px-3 py-1 rounded text-xs font-medium transition-colors',
  subsystem.enabled
    ? 'bg-green-100 text-green-700 hover:bg-green-200'
    : 'bg-gray-100 text-gray-600 hover:bg-gray-200'
)}>
  {subsystem.enabled ? 'AUTO-RUN' : 'DISABLED'}
</button>

Option 4: Better Disabled State

Keep current layout but improve disabled state clarity.

Benefits:

• Minimal change
• Clearer state communication
• Maintains all current functionality

Implementation:

// When disabled, show lock icon and make it obviously inactive
{!subsystem.enabled && <Lock className="text-gray-400 mr-1" />}
<span className={!subsystem.enabled ? 'text-gray-400 line-through' : ''}>
  {subsystem.auto_run ? 'AUTO' : 'MANUAL'}
</span>

ETHOS Compliance Considerations

✅ "Less is more" - Avoid over-decoration, keep it functional ✅ "Honest tool" - States must be immediately clear to technical users
✅ No marketing fluff - No gradients, shadows, or enterprise UI patterns ✅ Color-blind accessibility - Use icons/borders, not just color ✅ Developer-focused - Clear, concise, technical language

Recommendation

Consider Option 2 (Lucide Icons) as it:

• Maintains current functionality
• Adds clarity without complexity
• Uses existing icon library
• Improves accessibility
• Stays minimalist

Questions for Discussion

1. Should AUTO/MANUAL be a separate control or integrated with ON/OFF?
2. How important is the use case of "enabled but manual" vs "disabled entirely"?
3. Should we A/B test different approaches with actual users?
4. Does the current design meet accessibility standards (WCAG)?

Related Code

• aggregator-web/src/components/AgentHealth.tsx lines 358-387
• Uses cn() utility for conditional classes
• Current colors: green (ON), blue (AUTO), gray (OFF/MANUAL/disabled)
• Button sizes: text-xs, px-3 py-1

Next Steps

1. Decide on approach (enhance current vs simplify)
2. Get user feedback if possible
3. Implement chosen solution
4. Update documentation
5. Test with color-blind users