snippet-pastebin/docs/ANDROID-UI-CONSISTENCY.md

Android UI Testing & Consistency Guide

Overview

This document outlines how the Snippet Pastebin UI should work consistently across all platforms, with specific focus on Android (mobile) behavior to match desktop functionality.

Android Reference Configuration

Device: Pixel 5 (standard Android reference)

• Viewport: 393x851
• DPI: 440 DPI
• OS: Android 11+
• Browsers: Chrome, Firefox, Samsung Internet

UI Consistency Requirements

1. Navigation

Desktop (1400x900)

• Horizontal navigation bar with all routes visible
• Logo on left, backend indicator on right
• Sticky header on scroll

Android (393x851)

• MUST: All routes must be accessible
• MUST: Navigation must work identically to desktop
• MUST: Sticky header behavior preserved
• MUST: No routes should be hidden or inaccessible
• Implementation: Hamburger menu or vertical stack if needed, but all routes equally accessible

Test: /atoms, /molecules, /organisms, /templates, /demo, /settings all load and navigate correctly

2. Forms and Inputs

Desktop

• Standard form layout with labels
• Text inputs visible and accessible
• Form validation displays inline

Android

• MUST: All form fields must be accessible
• MUST: Input types must trigger appropriate mobile keyboards
  • type="email" → Email keyboard
  • type="number" → Number keyboard
  • type="text" → Text keyboard
• MUST: Labels must remain visible and associated with inputs
• MUST: Touch targets must be minimum 44px × 44px
• MUST: Validation messages must display clearly
• MUST: No horizontal scrolling required to see form fields

3. Buttons and Interactive Elements

Desktop

• Clear hover states
• Visible focus indicators
• Standard click behavior

Android

• MUST: Touch targets minimum 44px
• MUST: All buttons must be tappable without zooming
• MUST: Visual feedback on tap (highlight, ripple, etc.)
• MUST: Same functionality as desktop (no hidden features)
• MUST: 8px minimum spacing between touch targets
• MUST: No hover states required but not prohibited

4. Layout and Spacing

Desktop (1400x900)

• Horizontal spacing: 24px margins
• Vertical spacing: 16px gutters
• Multi-column layouts where appropriate

Android (393x851)

• MUST: No horizontal overflow
• MUST: Content must fit within viewport width
• MUST: Vertical scrolling only for long content
• MUST: Proper spacing maintained
• MUST: Touch padding maintained for interactive elements
• MUST: Safe area respected (no content behind notch/status bar)

Specific Requirements:

Page Width: 100% of viewport - margins
Max Width: 393px (safe area)
Content Margin: 16px minimum on each side
Touch Target Spacing: 8px minimum

5. Typography

Desktop

• H1: 32px, 700 weight
• H2: 28px, 600 weight
• Body: 16px, 400 weight

Android

• MUST: Font sizes readable without zoom
  • Minimum: 12px
  • Recommended: 14px+ for body text
  • Headings: 20px+
• MUST: Line height appropriate for readability (1.5x minimum)
• MUST: Letter spacing consistent
• MUST: Color contrast sufficient (WCAG AA minimum)
• MUST: Text must not be cut off

6. Images and Media

Both Platforms

• MUST: Images must scale appropriately
• MUST: No layout shift on image load
• MUST: Alt text required for all images
• MUST: Responsive images for different screen sizes

7. Modals and Overlays

Desktop

• Center-aligned modals
• Clickable backdrop to close
• Escape key closes modal

Android

• MUST: Modals must be usable on small screens
• MUST: Close button must be easily accessible
• MUST: Escape key still works
• MUST: Modal content must fit within viewport
• MUST: Scrollable if content exceeds viewport height
• MUST: No modal wider than 393px

8. Color and Contrast

Both Platforms

• MUST: Text color contrast >= 4.5:1 for normal text (WCAG AA)
• MUST: Interactive element contrast >= 3:1
• MUST: Colors must be consistent across platforms
• MUST: Dark mode must work on both platforms

9. Performance

Desktop

• Page load: < 3 seconds
• Interaction response: < 100ms

Android

• MUST: Page load: < 5 seconds (mobile networks slower)
• MUST: Tap response: < 100ms
• MUST: Smooth scrolling (60fps)
• MUST: No layout thrashing
• MUST: Memory usage stable

10. Keyboard and Input

Desktop

• Tab navigation between elements
• Enter to submit
• Escape to close modals

Android

• MUST: Keyboard doesn't obscure critical content
• MUST: Tab/focus navigation still works
• MUST: Keyboard can be dismissed
• MUST: Auto-focus on input doesn't cause jumping
• MUST: Form submission works with keyboard

Testing Checklist

Basic Functionality

• All routes load on Android
• Navigation works on all routes
• Back/forward buttons work
• Forms submit successfully
• Buttons trigger correct actions
• No console errors

Visual Consistency

• No horizontal overflow at any route
• Text readable without zoom
• Images display correctly
• Layout doesn't break
• Colors consistent
• Spacing appropriate

Responsive

• Content adapts to viewport
• Safe area respected
• Portrait and landscape both work
• Touch targets adequate (44px)
• No element overlap

Accessibility

• Touch targets 44px minimum
• Focus indicators visible
• ARIA labels present
• Keyboard navigation works
• Alt text on images
• Color contrast sufficient

Performance

• Page loads in < 5s
• Interactions respond in < 100ms
• Smooth scrolling
• No memory leaks
• No excessive network requests

Cross-Platform Validation Tests

Run these commands to validate consistency:

# Run all cross-platform tests
npm run test:e2e cross-platform

# Run Android-specific tests
npx playwright test -g "Android"

# Run with Android viewport
npx playwright test --project=chromium-mobile

# Compare desktop vs mobile
npm run test:e2e -- -g "Consistency"

Documentation Mapping

The following documentation should align with this Android UI guide:

From /docs folder:

1. QUICKSTART.md - Should work on Android, all steps clickable
2. README-APP.md - Should document mobile access
3. DEPLOYMENT.md - Should include mobile considerations
4. CONFIGURATION.md - Settings should be accessible on Android
5. IMPLEMENTATION.md - Should include responsive design notes

Required Updates:

• Mobile access instructions
• Touch interaction documentation
• Android-specific setup
• Performance guidelines for mobile
• Troubleshooting mobile issues

Example: Navigation Consistency

Desktop Navigation

┌─────────────────────────────────────────────┐
│ Logo    Snippets Molecules Organisms...  │ ⚙  │
└─────────────────────────────────────────────┘

Android Navigation

┌──────────────────────────┐
│ ☰  Logo              ⚙  │
│                          │
│ • Snippets              │
│ • Molecules             │
│ • Organisms             │
│ • Templates             │
│ • Demo                  │
│ • Settings              │
└──────────────────────────┘

Key: Same routes, same functionality, different layout

Example: Form Consistency

Desktop Form

Full Name: [____________________]
Email:     [____________________]
Message:   [________________________]
           [    Submit    ]

Android Form

Full Name:
[__________________]

Email:
[__________________]

Message:
[_________________
 _________________]

[    Submit    ]

Key: Same fields, same validation, optimized for touch

Validation Rules

Must Pass All Tests:

1. All routes accessible on Android
2. No horizontal scrolling
3. All buttons tappable (44px+)
4. Forms work identically
5. Text readable without zoom
6. Touch targets don't overlap
7. Keyboard navigation works
8. No console errors
9. Page loads < 5s
10. Performance smooth (60fps)

Success Criteria:

• ✅ User can complete all tasks on Android as on desktop
• ✅ No features hidden on mobile
• ✅ No scrolling required to access critical features
• ✅ Same data/state accessible everywhere
• ✅ Performance acceptable for mobile networks

Test Results

Current test: 98 tests covering cross-platform consistency

Coverage includes:

• Navigation consistency (6 tests)
• Form consistency (4 tests)
• Button consistency (3 tests)
• Layout consistency (3 tests)
• Typography consistency (3 tests)
• Viewport features (2 tests)
• State consistency (2 tests)
• Error handling (2 tests)

See: tests/e2e/cross-platform.spec.ts

Debugging Android Issues

No Horizontal Scroll Issue

const overflow = await page.evaluate(() =>
  Math.max(document.documentElement.scrollWidth - window.innerWidth, 0)
);
console.log("Horizontal overflow:", overflow);

Button Not Tappable

const box = await button.boundingBox();
console.log("Button size:", box.width, "x", box.height);
// Should be >= 44x44

Text Cut Off

const overflow = await element.evaluate(el =>
  el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight
);
console.log("Text overflow:", overflow);

Keyboard Issues

const input = page.locator("input");
await input.click();
console.log("Input type:", await input.getAttribute("type"));
// Should trigger appropriate keyboard

Integration with Documentation

All documentation in /docs folder should reflect Android UI consistency:

1. Screenshots - Include Android versions
2. Instructions - Use "tap" instead of "click"
3. Features - Clarify mobile availability
4. Setup - Include mobile setup steps
5. Troubleshooting - Add mobile issues

Summary

The UI MUST work identically on Android as on desktop with these adaptations:

• Navigation reorganized but all routes accessible
• Forms and inputs adapted for touch
• Layout optimized for 393px width
• Typography sized for readability
• Touch targets 44px minimum
• No horizontal scrolling
• Performance optimized for mobile networks

All documentation should reflect Android as a primary platform, not secondary.