ezsepa-website/README.md

# EzSepa Bank Payment - Landing Page

Production-ready, responsive, accessible static landing page for the EzSepa Bank Payment Shopify app. Built with TailwindCSS, Vite, and vanilla JavaScript.

## 📁 Project Structure

```
ezsepa/
├── index.html              # Main landing page
├── styles.css              # TailwindCSS styles with custom utilities
├── main.js                 # JavaScript for interactivity and analytics
├── package.json            # Dependencies and build scripts
├── tailwind.config.js      # TailwindCSS configuration
├── postcss.config.js       # PostCSS configuration
├── i18n-keys.json         # Internationalization keys for integration
├── assets/                 # Image assets and placeholders
│   ├── hero.png           # Dashboard hero image (SVG placeholder)
│   ├── checkout.png       # Checkout extension screenshot (SVG)
│   ├── analytics.png      # Analytics dashboard screenshot (SVG)
│   └── favicon.svg        # App favicon
└── README.md              # This file
```

## 🚀 Quick Start

### 1. Install Dependencies

```powershell
npm install
```

This will install:
- Vite (v5.0.0) - Fast development server and build tool
- TailwindCSS (v3.4.0) - Utility-first CSS framework
- PostCSS (v8.4.32) - CSS transformation
- Autoprefixer (v10.4.16) - Auto-add vendor prefixes

### 2. Development Server

```powershell
npm run dev
```

Opens development server at `http://localhost:5173` with hot module reload.

### 3. Build for Production

```powershell
npm run build
```

Generates optimized production files in `dist/` folder:
- Minified HTML, CSS, and JS
- Optimized assets
- Ready for deployment

### 4. Preview Production Build

```powershell
npm run preview
```

Preview the production build locally at `http://localhost:5174`.

## 🎨 Design Overview

**Modern, clean landing page** with Shopify-esque aesthetic using:
- **Color palette**: Brand blue (#0A66C2), success green (#00875A), warning yellow (#FFAB00)
- **Typography**: System font stack (system-ui, Segoe UI, Roboto, etc.)
- **Responsive breakpoints**: Mobile-first → 640px → 1024px
- **Animations**: Fade-in-up, float effects, smooth scrolling

## 🔧 Customization Guide

### 1. Replace Placeholder Links

**Search and replace these placeholders** in `index.html`:

- `{INSTALL_LINK}` → Your Shopify App Store URL (e.g., `https://apps.shopify.com/ezsepa-bank-payment`)
- `{DEMO_LINK}` → Demo video or interactive demo URL
- `https://github.com/your-repo` → Your actual GitHub repository URL

**Quick PowerShell find/replace:**

```powershell
(Get-Content index.html) -replace '\{INSTALL_LINK\}', 'https://apps.shopify.com/your-app' | Set-Content index.html
(Get-Content index.html) -replace '\{DEMO_LINK\}', 'https://youtu.be/demo-video' | Set-Content index.html
(Get-Content index.html) -replace 'https://github.com/your-repo', 'https://github.com/yourname/auto-bank-payment' | Set-Content index.html
```

### 2. Replace Asset Images

**Current assets are SVG placeholders.** Replace with real screenshots:

#### Option A: Use existing repo images

If your main repo (`auto-bank-payment`) has images in `web/client/src/assets/images/`:

```powershell
# Copy from main repo to landing page
Copy-Item "../auto-bank-payment/web/client/src/assets/images/hero.png" "./assets/hero.png"
Copy-Item "../auto-bank-payment/web/client/src/assets/images/analytics.png" "./assets/analytics.png"
Copy-Item "../auto-bank-payment/web/client/src/assets/images/checkout.png" "./assets/checkout.png"
```

#### Option B: Take new screenshots

1. **Hero image** (`assets/hero.png`): Dashboard showing QR codes and analytics (1200×800px recommended)
2. **Checkout image** (`assets/checkout.png`): Thank-you page with QR code extension (1200×700px)
3. **Analytics image** (`assets/analytics.png`): Analytics dashboard with charts (800×600px)

**Optimize images before deploying:**
```powershell
# Install optimization tools (optional)
npm install -D vite-plugin-imagemin
```

### 3. Configure Analytics

**Edit `main.js`** around line 100 to integrate your analytics provider:

```javascript
// Replace this stub with your analytics
window._ezsepa = window._ezsepa || {
  track: (eventName, properties = {}) => {
    // Option 1: Google Analytics
    gtag('event', eventName, properties);
    
    // Option 2: Plausible
    plausible(eventName, { props: properties });
    
    // Option 3: Custom endpoint
    fetch('/api/track', {
      method: 'POST',
      body: JSON.stringify({ event: eventName, ...properties })
    });
  }
};
```

**Add your tracking ID** in `index.html` (before `</head>`):

```html
<!-- Google Analytics example -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>
```

### 4. Internationalization Integration

**File: `i18n-keys.json`** contains all landing page copy as structured JSON.

**To integrate with main repo Vue i18n** (`web/client/src/locales/en.json`):

```json
// In web/client/src/locales/en.json, merge:
{
  "landing": {
    "hero": {
      "title": "EzSepa Bank Payment for Shopify",
      // ... rest from i18n-keys.json
    }
  }
}
```

Then update `index.html` to use Vue i18n keys:

```html
<h1>{{ $t('landing.hero.title') }}</h1>
```

**For static site**, keep as-is or use a static i18n library like:
- `i18next` (https://www.i18next.com/)
- `rosetta` (https://github.com/lukeed/rosetta)

### 5. Color Customization

**Edit `tailwind.config.js`** to change brand colors:

```javascript
colors: {
  brand: {
    50: '#e6f1ff',     // Lightest brand color
    500: '#0A66C2',    // Primary brand color
    600: '#085299',    // Hover state
    700: '#063e73',    // Darkest brand color
  },
  success: '#00875A',  // Success/confirmation green
  warning: '#FFAB00',  // Warning yellow
  error: '#DE350B',    // Error red
}
```

Or use **CSS variables** in `styles.css`:

```css
:root {
  --color-brand-primary: #0A66C2;
  --color-brand-hover: #085299;
  --color-success: #00875A;
}
```

## 📦 Deployment

### Option 1: Shopify App Hosting (Recommended)

If integrating with the main Shopify app:

1. **Move to main repo** under `web/landing/`:
   ```powershell
   Move-Item -Path "." -Destination "../auto-bank-payment/web/landing" -Force
   ```

2. **Update Shopify app routing** (Node/Express backend):
   ```javascript
   // In web/server.js or similar
   app.use('/landing', express.static(path.join(__dirname, 'landing/dist')));
   ```

3. **Deploy with app** via Shopify CLI:
   ```powershell
   cd ../auto-bank-payment
   shopify app deploy
   ```

### Option 2: Static Hosting (Netlify, Vercel, Cloudflare Pages)

**Netlify:**
```powershell
# Install Netlify CLI
npm install -g netlify-cli

# Build and deploy
npm run build
netlify deploy --prod --dir=dist
```

**Vercel:**
```powershell
npm install -g vercel
vercel --prod
```

**GitHub Pages:**
```powershell
npm run build
# Push dist/ to gh-pages branch
```

### Option 3: Custom Server

Upload `dist/` folder contents to your web server:
```powershell
# Example: Upload via FTP, rsync, or SCP
scp -r dist/* user@yourserver.com:/var/www/ezsepa/
```

## 🔍 SEO Checklist

- [x] Meta title and description in `<head>`
- [x] Open Graph tags for social sharing
- [x] JSON-LD structured data (SoftwareApplication schema)
- [x] Semantic HTML5 (`<nav>`, `<section>`, `<footer>`)
- [x] Alt text for all images
- [x] Mobile-responsive design
- [ ] **Replace placeholder hero image** in og:image meta tag
- [ ] **Add robots.txt** if needed (allow all by default)
- [ ] **Add sitemap.xml** for better indexing
- [ ] **Submit to Google Search Console** after deployment

**Add `robots.txt`** (optional):
```txt
User-agent: *
Allow: /

Sitemap: https://yourapp.com/sitemap.xml
```

## ♿ Accessibility Features

- ✅ Semantic HTML5 structure
- ✅ ARIA labels on interactive elements
- ✅ Keyboard navigation support (Tab, Enter, Space)
- ✅ Focus indicators for keyboard users
- ✅ Alt attributes on all images
- ✅ Sufficient color contrast (WCAG AA compliant)
- ✅ Reduced motion support for animations
- ✅ Screen reader friendly navigation

**Test accessibility:**
- Lighthouse audit in Chrome DevTools (aim for 90+ score)
- [WAVE browser extension](https://wave.webaim.org/)
- Keyboard-only navigation test

## 🎯 Performance Optimization

**Already optimized:**
- Minified CSS/JS in production build
- Modern CSS with no heavy frameworks
- Lazy-loaded images (except hero)
- Lightweight JavaScript (~10KB gzipped)
- Vite's code splitting and tree-shaking

**Further optimizations:**
```javascript
// In vite.config.js (create if needed)
export default {
  build: {
    minify: 'terser',
    terserOptions: {
      compress: {
        drop_console: true, // Remove console.logs
      },
    },
  },
};
```

**Compress images:**
Use tools like TinyPNG, Squoosh, or ImageOptim before adding to `assets/`.

## 🐛 Troubleshooting

### Issue: TailwindCSS not applying styles

**Solution:** Ensure dev server is running and `tailwind.config.js` `content` array includes all HTML files:
```javascript
content: [
  "./index.html",
  "./*.html",
  "./src/**/*.{js,jsx,ts,tsx}"
]
```

### Issue: Mobile menu not toggling

**Solution:** Check browser console for JavaScript errors. Ensure `main.js` is loaded:
```html
<script type="module" src="/main.js"></script>
```

### Issue: Images not loading

**Solution:** 
1. Check file paths are correct (`/assets/hero.png` not `assets/hero.png`)
2. Ensure images exist in `assets/` folder
3. Run `npm run dev` to see 404 errors in console

### Issue: Build fails

**Solution:**
```powershell
# Clear node_modules and reinstall
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install
npm run build
```

## 📚 Tech Stack Summary

| Technology | Version | Purpose |
|------------|---------|---------|
| **Vite** | 5.0.0 | Lightning-fast dev server and build tool |
| **TailwindCSS** | 3.4.0 | Utility-first CSS framework |
| **PostCSS** | 8.4.32 | CSS transformation and processing |
| **Autoprefixer** | 10.4.16 | Automatic vendor prefixes |
| **Vanilla JS** | ES6+ | Lightweight, no framework overhead |

**No jQuery, no React, no heavy dependencies** — just fast, accessible HTML/CSS/JS.

## 🔗 Integration with Main Repo

**If moving this landing page into `auto-bank-payment` repo:**

1. **Copy to main repo:**
   ```powershell
   Copy-Item -Path "." -Destination "../auto-bank-payment/web/landing" -Recurse
   ```

2. **Update main repo's `package.json`** to include landing scripts:
   ```json
   {
     "scripts": {
       "landing:dev": "cd web/landing && npm run dev",
       "landing:build": "cd web/landing && npm run build"
     }
   }
   ```

3. **Serve from Express backend:**
   ```javascript
   // In web/backend/index.js or server.js
   app.use('/landing', express.static(path.join(__dirname, '../landing/dist')));
   ```

4. **Update app navigation** to link to `/landing` for marketing page.

## 📝 Content TODO Checklist

Before going live, complete these tasks:

- [ ] Replace `{INSTALL_LINK}` with Shopify App Store URL
- [ ] Replace `{DEMO_LINK}` with demo video or interactive tour
- [ ] Swap `assets/hero.png`, `checkout.png`, `analytics.png` with real screenshots
- [ ] Add analytics tracking code (Google Analytics, Plausible, etc.)
- [ ] Update GitHub repository links
- [ ] Add contact email in footer (currently `contact@ezsepa.com` placeholder)
- [ ] Review and adjust pricing (currently €0/€19/€49/Custom)
- [ ] Test all links and CTAs
- [ ] Run Lighthouse audit and fix issues
- [ ] Test on mobile devices (iOS Safari, Chrome Android)
- [ ] Proofread all copy for typos and accuracy
- [ ] Add real favicon if different from placeholder
- [ ] Set up custom domain or subdomain (e.g., `ezsepa.com` or `landing.yourapp.com`)

## 🆘 Support & Resources

- **Main repo**: [auto-bank-payment](../auto-bank-payment) (if integrated)
- **Shopify App docs**: https://shopify.dev/docs/apps
- **TailwindCSS docs**: https://tailwindcss.com/docs
- **Vite docs**: https://vitejs.dev/
- **Accessibility guide**: https://www.w3.org/WAI/WCAG21/quickref/

## 📄 License

Same license as the main EzSepa Bank Payment Shopify app. See main repository for details.

---

**Built with ❤️ for EU merchants accepting SEPA payments**

For questions or issues, open a GitHub issue in the main repository.