xpeditis2.0/apps/frontend/public/assets/README.md

Assets Directory

This directory contains all static assets for the Xpeditis frontend application.

Directory Structure

public/assets/
├── images/          # General images (hero banners, backgrounds, photos)
├── logos/           # Company logos and branding assets
└── icons/           # UI icons and small graphics

Usage in Components

Next.js Image Component (Recommended)

import Image from 'next/image';

export function Hero() {
  return (
    <Image
      src="/assets/images/hero-banner.jpg"
      alt="Maritime shipping"
      width={1920}
      height={1080}
      priority
    />
  );
}

Logo Usage

import Image from 'next/image';

export function Header() {
  return (
    <Image
      src="/assets/logos/xpeditis-logo.svg"
      alt="Xpeditis"
      width={150}
      height={40}
    />
  );
}

Icons

// SVG icons can be imported directly
import ShippingIcon from '@/public/assets/icons/shipping-icon.svg';

export function FeatureCard() {
  return (
    <div>
      <ShippingIcon className="w-8 h-8 text-blue-600" />
      <h3>Fast Shipping</h3>
    </div>
  );
}

// Or use Image component
import Image from 'next/image';

export function IconButton() {
  return (
    <Image
      src="/assets/icons/notification-icon.svg"
      alt="Notifications"
      width={24}
      height={24}
    />
  );
}

File Naming Conventions

Images

• Use kebab-case: hero-banner.jpg, shipping-container.png
• Include descriptive names: maritime-port-sunset.jpg
• Use appropriate formats:
  • Photos: .jpg (compressed, smaller file size)
  • Graphics with transparency: .png
  • Simple graphics/illustrations: .svg

Logos

• Main logo: xpeditis-logo.svg
• Dark mode variant: xpeditis-logo-dark.svg
• Light mode variant: xpeditis-logo-light.svg
• Icon only: xpeditis-icon.svg
• Favicon sizes: favicon-16x16.png, favicon-32x32.png

Icons

• Use .svg format for scalability
• Name by function: tracking-icon.svg, dashboard-icon.svg
• Keep icons monochrome (colorize via CSS)

Optimization Guidelines

Image Optimization

1. Compress images before adding to repository

   • Use tools like TinyPNG, ImageOptim, or Squoosh
   • Target: < 200KB for hero images, < 50KB for thumbnails

2. Use appropriate dimensions

   • Hero banners: 1920x1080px
   • Thumbnails: 400x300px
   • Profile images: 200x200px

3. Leverage Next.js Image Optimization

   • Always use <Image> component instead of <img>
   • Specify width and height props
   • Use priority for above-the-fold images
   • Use loading="lazy" for below-the-fold images

SVG Optimization

• Remove unnecessary metadata with SVGO
• Keep viewBox attribute for proper scaling
• Use currentColor for icons to inherit text color

Example Assets for Xpeditis

Recommended Images

• hero-container-ship.jpg - Homepage hero banner
• tracking-dashboard.png - Dashboard screenshot
• team-photo.jpg - About us page
• port-operations.jpg - Services page
• global-map.svg - Shipping routes visualization

Recommended Icons

• container-icon.svg - Container/booking icon
• ship-icon.svg - Shipping/tracking icon
• document-icon.svg - Documentation icon
• clock-icon.svg - Transit time icon
• location-icon.svg - Port location icon
• notification-icon.svg - Alerts/notifications
• user-icon.svg - User profile
• settings-icon.svg - Settings/preferences

Adding New Assets

1. Check file size - Ensure images are optimized
2. Use correct directory - images/ for photos, logos/ for branding, icons/ for UI
3. Follow naming convention - kebab-case, descriptive names
4. Update this README - Document any special assets or usage patterns
5. Test responsiveness - Verify assets look good on mobile and desktop

CDN Considerations (Future)

For production, consider moving to a CDN:

• AWS S3 + CloudFront
• Cloudinary
• Vercel Image Optimization (automatic with Next.js)

Current setup serves from /public which is fine for development and small-scale production.

License & Attribution

Ensure all assets have proper licensing:

• Company logos: Internal use approved
• Stock photos: Properly licensed (e.g., Unsplash, Pexels)
• Icons: Open source (e.g., Heroicons, Lucide) or purchased license

Document attributions in /public/assets/ATTRIBUTIONS.md if required.