AeThex-OS/docs/PLATFORM_UI_GUIDE.md

Platform-Specific UI Guide

Overview

AeThex OS now supports platform-adaptive UI that automatically adjusts for mobile, desktop, and web environments while maintaining the same core functionality.

Quick Start

1. Use the Platform Layout Hook

import { usePlatformLayout, usePlatformClasses } from '@/hooks/use-platform-layout';

function MyComponent() {
  const layout = usePlatformLayout();
  const classes = usePlatformClasses();

  return (
    <div className={classes.container}>
      {layout.isMobile ? (
        <MobileView />
      ) : (
        <DesktopView />
      )}
    </div>
  );
}

2. Platform-Specific Rendering

import { PlatformSwitch } from '@/hooks/use-platform-layout';

<PlatformSwitch
  mobile={<MobileNavigation />}
  desktop={<DesktopNavigation />}
  web={<WebNavigation />}
  fallback={<DefaultNavigation />}
/>

3. Adaptive Styling

const classes = usePlatformClasses();

<Button className={classes.button}>
  {/* Automatically h-12 on mobile, h-10 on desktop/web */}
  Click Me
</Button>

Platform Detection

The app automatically detects:

• Mobile: Capacitor native apps (iOS/Android)
• Desktop: Tauri desktop apps (Windows/macOS/Linux)
• Web: Browser-based access

Detection is done via the existing lib/platform.ts.

Layout Patterns

Mobile-First Approach

// Mobile: Bottom navigation, full-width cards, larger touch targets
<div className="grid grid-cols-1 gap-3 px-4">
  <Card className="rounded-lg p-4">
    <Button className="h-12 text-base w-full">
      Large Touch Target
    </Button>
  </Card>
</div>

Desktop Optimization

// Desktop: Top navigation, multi-column layout, compact controls
<div className="grid grid-cols-3 gap-6 px-8">
  <Card className="rounded-xl p-6">
    <Button className="h-10 text-sm">
      Compact Button
    </Button>
  </Card>
</div>

Responsive Design Strategy

1. Layout Changes

• Mobile: Single column, bottom navigation, full-screen modals
• Desktop: Multi-column, top/side navigation, floating dialogs
• Web: Adaptive columns, sticky navigation, responsive dialogs

2. Typography

• Mobile: Larger base font (16px+) for readability
• Desktop: Standard font (14px) for information density
• Web: Medium font (15px) for balance

3. Spacing

• Mobile: Tighter spacing (12px-16px) to maximize screen space
• Desktop: Generous spacing (24px-32px) for clarity
• Web: Balanced spacing (16px-24px)

4. Touch Targets

• Mobile: Minimum 44px height for buttons and interactive elements
• Desktop: Standard 40px height
• Web: 40px height

Example Implementation

See PlatformAdaptiveExample.tsx for a complete example showing:

• Platform-specific headers
• Adaptive grids
• Conditional navigation styles
• Touch-optimized controls

Common Patterns

Adaptive Navigation

function Navigation() {
  const { isMobile } = usePlatformLayout();

  if (isMobile) {
    return (
      <nav className="fixed bottom-0 left-0 right-0 border-t">
        <BottomTabBar />
      </nav>
    );
  }

  return (
    <nav className="fixed top-0 left-0 right-0 border-b">
      <TopMenuBar />
    </nav>
  );
}

Responsive Cards

function CardGrid() {
  const { isMobile, isDesktop } = usePlatformLayout();
  
  const columns = isMobile ? 'grid-cols-1' : 
                  isDesktop ? 'grid-cols-4' : 
                  'grid-cols-2';

  return <div className={`grid ${columns} gap-4`}>
    {/* Cards */}
  </div>;
}

Adaptive Forms

function Form() {
  const classes = usePlatformClasses();
  
  return (
    <form className={classes.spacing}>
      <Input className={classes.input} placeholder="Name" />
      <Button className={classes.button} type="submit">
        Submit
      </Button>
    </form>
  );
}

Mobile-Specific Features

Safe Area Support (iOS)

/* In your CSS */
.mobile-container {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

Pull-to-Refresh

import { isMobile } from '@/lib/platform';

if (isMobile()) {
  // Enable pull-to-refresh gesture
  window.addEventListener('touchstart', handlePullToRefresh);
}

Native Gestures

// Swipe navigation on mobile
if (isMobile()) {
  <SwipeableViews onChangeIndex={handleSwipe}>
    <Page1 />
    <Page2 />
  </SwipeableViews>
}

Desktop-Specific Features

Window Controls

import { isDesktop } from '@/lib/platform';

if (isDesktop()) {
  // Custom title bar, minimize/maximize/close
  <TauriTitleBar />
}

Keyboard Shortcuts

if (isDesktop()) {
  useEffect(() => {
    // Ctrl+N for new item, etc.
    const handler = (e: KeyboardEvent) => {
      if (e.ctrlKey && e.key === 'n') {
        createNew();
      }
    };
    window.addEventListener('keydown', handler);
    return () => window.removeEventListener('keydown', handler);
  }, []);
}

Testing Platform Variants

In Development

// Force platform detection for testing
if (import.meta.env.DEV) {
  window.Capacitor = {}; // Test as mobile
  // or
  window.__TAURI__ = {}; // Test as desktop
}

Chrome DevTools

• Open DevTools → Device Toolbar
• Select mobile device
• The app will detect as web but use mobile viewport

Best Practices

1. Design Mobile-First: Start with mobile constraints, enhance for larger screens
2. Use Touch-Friendly Sizes: Minimum 44px tap targets on mobile
3. Optimize Navigation: Bottom tabs on mobile, top/side on desktop
4. Adapt Typography: Larger on mobile, more compact on desktop
5. Test on Real Devices: Emulators are good, but test on actual hardware
6. Progressive Enhancement: Core functionality works everywhere, enhancements per platform

Migration Guide

To update existing components:

1. Import the hooks:

import { usePlatformClasses } from '@/hooks/use-platform-layout';

2. Replace hardcoded classes:

// Before
<div className="px-6 py-4">

// After
const classes = usePlatformClasses();
<div className={classes.container}>

3. Add platform switches where needed:

<PlatformSwitch
  mobile={<MobileComponent />}
  fallback={<DesktopComponent />}
/>

Resources

• Platform Detection
• Layout Hook
• Example Component
• Capacitor Docs
• Tauri Docs