# Mobile App Builder Template

A mobile-first template for building cross-platform applications with Next.js 15, TypeScript, and @hanzo/ui components.

## Features

- ✨ Built with **@hanzo/ui** component library (shadcn/ui based)
- 📱 **Mobile-first** design approach
- 🎨 **Monochromatic color scheme** for clean aesthetics
- 📐 **Fully responsive** (mobile, tablet, desktop)
- 🌙 **Dark mode** support with next-themes
- 🚀 **Next.js 15** App Router with React 19
- 📲 **Touch-optimized** components
- ⚡ **TypeScript strict mode** enabled
- 🎯 **PWA-ready** architecture

## Quick Start

### Installation

```bash
# Install dependencies
npm install

# Start development server
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) on your mobile device or desktop browser.

### Production Build

```bash
# Create production build
npm run build

# Start production server
npm start
```

## Project Structure

```
mobile/
├── app/                  # Next.js App Router
│   ├── layout.tsx       # Root layout with viewport
│   └── page.tsx         # Home page
├── components/          # React components
│   └── sections/        # Page sections
│       ├── hero.tsx     # Hero section (mobile-optimized)
│       └── features.tsx # Features grid (touch-friendly)
├── lib/                 # Utilities and config
│   └── site.ts          # Site configuration
├── public/              # Static assets & icons
└── package.json         # Dependencies
```

## Component Usage

All components are imported from `@hanzo/ui` and optimized for mobile:

```tsx
import { Button, Card, CardContent, CardHeader, CardTitle } from '@hanzo/ui/components'

// Mobile-optimized button
<Button size="lg" className="w-full sm:w-auto">
  Download App
</Button>

// Touch-friendly card
<Card className="hover:shadow-lg transition-shadow">
  <CardHeader>
    <CardTitle>Feature</CardTitle>
  </CardHeader>
  <CardContent>
    Mobile-optimized content
  </CardContent>
</Card>
```

## Mobile-First Design Patterns

### Responsive Breakpoints

```css
/* Mobile First Approach */
- Base: 320px (minimum mobile)
- sm: 640px (large phones)
- md: 768px (tablets)
- lg: 1024px (desktops)
- xl: 1280px (large screens)
```

### Touch Targets

All interactive elements follow mobile best practices:
- Minimum touch target: 44x44px
- Adequate spacing between tappable elements
- Clear visual feedback on touch

### Mobile Navigation

```tsx
// Example mobile-friendly navigation
<nav className="fixed bottom-0 sm:relative sm:bottom-auto">
  {/* Tab bar for mobile, top nav for desktop */}
</nav>
```

## Customization

### Site Configuration

Edit `lib/site.ts` to customize your app details:

```typescript
export const siteConfig = {
  name: "Your App Name",
  tagline: "Your App Tagline",
  description: "What your app does",
  url: "https://your-app.com",
  features: [
    "Feature 1",
    "Feature 2",
    "Feature 3",
    "Feature 4"
  ]
}
```

### Styling

The template uses a monochromatic color scheme:

- Primary: Black (`#000000`)
- Secondary: Gray (`#666666`)
- Background: White/Dark gray
- Text: High contrast for readability

### Adding Pages

Create mobile-optimized pages:

```tsx
// app/features/page.tsx
import { Button, Card } from '@hanzo/ui/components'

export default function FeaturesPage() {
  return (
    <div className="container mx-auto py-8 px-4">
      <h1 className="text-2xl sm:text-4xl font-bold">
        Features
      </h1>
      {/* Mobile-first content */}
    </div>
  )
}
```

## Mobile Features

### Progressive Web App (PWA)
- Installable on mobile devices
- Offline capability
- App-like experience

### Touch Gestures
- Swipe navigation support
- Pull-to-refresh patterns
- Smooth scrolling

### Performance Optimization
- Lazy loading for images
- Code splitting by route
- Minimal bundle size
- Optimized for 3G connections

### Device Features
- Responsive viewport meta tag
- Safe area insets for notches
- Orientation change handling
- Native app feel

## Available Scripts

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm run build` | Build for production |
| `npm start` | Start production server |
| `npm run lint` | Run ESLint |

## Testing on Mobile Devices

### Local Network Testing

```bash
# Start dev server on all network interfaces
npm run dev -- --hostname 0.0.0.0

# Access from mobile device
http://[YOUR_LOCAL_IP]:3000
```

### Mobile Debugging

- Chrome DevTools: Remote debugging for Android
- Safari Web Inspector: iOS debugging
- Responsive Design Mode: Desktop browser testing

## Environment Variables

Create a `.env.local` file:

```env
# Example environment variables
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_NAME=MobileFirst
NEXT_PUBLIC_ANALYTICS_ID=UA-...
```

## Responsive Components

All components adapt to screen size:

```tsx
// Responsive grid
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">
  {/* Content */}
</div>

// Responsive typography
<h1 className="text-2xl sm:text-3xl md:text-4xl">
  Responsive Heading
</h1>

// Responsive spacing
<div className="p-4 sm:p-6 md:p-8">
  {/* Content */}
</div>
```

## TypeScript

Strict mode is enabled for type safety:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}
```

## Browser & Device Support

- iOS Safari 13+
- Chrome Mobile 89+
- Samsung Internet 13+
- Firefox Mobile 86+
- Edge Mobile 89+

## Performance Metrics

Target metrics for mobile:
- First Contentful Paint: < 1.8s
- Time to Interactive: < 3.9s
- Cumulative Layout Shift: < 0.1
- Lighthouse Score: > 90

## License

MIT

## Support

For questions or issues, visit [github.com/hanzoai/templates](https://github.com/hanzoai/templates)