Skip to content
CloudAlt Documentation

Asset Management Strategy

Date: October 11, 2025
Status: ✅ Implemented
Related: Component Architecture

Overview

Section titled “Overview”

This document defines where assets (images, icons, fonts) should live in the monorepo and when to use each location.

📂 Asset Locations

Section titled “📂 Asset Locations”

Two Asset Directories:

Section titled “Two Asset Directories:”
1. packages/assets/                          ← Monorepo-wide generic assets
2. apps/{division}/{brand}/shared/assets/   ← Brand-specific assets

🎯 Decision Tree

Section titled “🎯 Decision Tree”
Is this asset used by ALL divisions?
│
├─ YES ──→ Is it generic (not brand-specific)?
│   │
│   ├─ YES ──→ packages/assets/
│   │         Examples: arrow icons, generic UI icons, CloudAlt logo
│   │
│   └─ NO ──→ apps/{division}/{brand}/shared/assets/
│             Each brand has their own version
│
└─ NO ──→ apps/{division}/{brand}/shared/assets/
          Brand-specific content

📦 Monorepo-Wide Assets (packages/assets/)

Section titled “📦 Monorepo-Wide Assets (packages/assets/)”

Location:

Section titled “Location:”
packages/assets/
├── icons/
│   ├── arrows/          # Navigation arrows
│   ├── actions/         # Action icons (plus, trash, edit)
│   ├── navigation/      # Nav icons (home, menu)
│   └── social/          # Social media icons
├── illustrations/       # Generic illustrations
└── brand/
    └── logo/           # CloudAlt company logo

Use When:

Section titled “Use When:”
  • ✅ Asset is used across ALL divisions
  • ✅ Generic UI elements (not brand-specific)
  • ✅ Small file sizes (< 50KB ideally)
  • ✅ Company-wide branding (CloudAlt logo)

Examples:

Section titled “Examples:”
  • Generic arrow icons
  • Common action icons (plus, edit, delete)
  • Empty state illustrations
  • CloudAlt company logo

⚠️ Warning:

Section titled “⚠️ Warning:”

Assets here are bundled with every app. Keep this minimal!

Usage:

Section titled “Usage:”
// Web
import ArrowRight from '@cloudalt-frontend/assets/icons/arrows/arrow-right.svg';


// Mobile
import ArrowRight from '@cloudalt-frontend/assets/icons/arrows/arrow-right.svg';
import { SvgXml } from 'react-native-svg';

🎨 Brand-Specific Assets (apps/.../shared/assets/)

Section titled “🎨 Brand-Specific Assets (apps/.../shared/assets/)”

Location:

Section titled “Location:”
apps/stay_match/pinkguest/
  └── shared/
      └── assets/
          ├── images/
          │   ├── hero-background.png
          │   ├── hero-background@2x.png
          │   ├── logo.png
          │   └── feature-*.png
          └── fonts/
              └── CustomFont.woff2


apps/stay_match/orangeguest/
  └── shared/
      └── assets/
          ├── images/
          │   ├── hero-background.png    # Different from pinkguest!
          │   └── logo.png
          └── fonts/

Use When:

Section titled “Use When:”
  • ✅ Asset is unique to this brand
  • ✅ Shared between brand’s web and mobile apps
  • ✅ Brand identity assets (logos, hero images)
  • ✅ Any size (only bundled with this brand)

Examples:

Section titled “Examples:”
  • Hero background images
  • Brand-specific logos
  • Feature screenshots
  • Brand photos
  • Custom fonts

✅ Advantages:

Section titled “✅ Advantages:”
  • Only bundled with specific brand
  • Independent updates per brand
  • Clear ownership
  • Better performance

Usage:

Section titled “Usage:”
// Web
import heroImage from '../../shared/assets/images/hero-background.png';


// Mobile
const heroImage = require('../../shared/assets/images/hero-background.png');

📊 Asset Types by Location

Section titled “📊 Asset Types by Location”
Asset TypeLocationReason
Generic arrow iconpackages/assets/icons/arrows/Used everywhere
Generic edit iconpackages/assets/icons/actions/Used everywhere
CloudAlt company logopackages/assets/brand/logo/Company-wide
Empty state illustrationpackages/assets/illustrations/Used everywhere
Pinkguest hero imageapps/stay_match/pinkguest/shared/assets/images/hero/Brand-specific
Pinkguest logoapps/stay_match/pinkguest/shared/assets/images/logos/Brand-specific
Feature screenshotapps/{division}/{brand}/shared/assets/images/features/Brand-specific
Onboarding tutorialapps/{division}/{brand}/shared/assets/images/onboarding/Brand-specific
Default avatarapps/{division}/{brand}/shared/assets/images/avatars/Brand-specific
Custom brand fontapps/{division}/{brand}/shared/assets/fonts/Brand-specific

🎯 Asset Guidelines

Section titled “🎯 Asset Guidelines”

Images

Section titled “Images”

All brand-specific images are organized into folders by function within apps/{division}/{brand}/shared/assets/images/. This structure makes it easy to find images, manage them by category, and maintain consistency across teams.

Standard Folder Structure

Section titled “Standard Folder Structure”
apps/{division}/{brand}/shared/assets/images/
├── hero/           # Hero/banner images for landing pages
├── logos/          # Brand logos and wordmarks
├── features/       # Feature showcase images
├── onboarding/     # Tutorial and onboarding flow images
├── avatars/        # Default avatars and placeholders
└── misc/           # Other brand-specific images

Hero Backgrounds (images/hero/)

Section titled “Hero Backgrounds (images/hero/)”
  • Target size: < 300KB
  • Max size: 500KB
  • Format: WebP for web, PNG/JPG for mobile
  • Naming: hero-background.png, hero-background@2x.png
  • Usage: Landing pages, section headers, marketing material
  • Responsive: Provide @2x, @3x variants for mobile

Logos (images/logos/)

Section titled “Logos (images/logos/)”
  • Target size: < 25KB
  • Max size: 50KB
  • Format: PNG with transparency or SVG (preferred)
  • Provide sizes: logo.png, logo@2x.png, logo@3x.png
  • Examples: logo.png, logo-white.png, logo-icon.png

Feature Images (images/features/)

Section titled “Feature Images (images/features/)”
  • Target size: < 100KB
  • Max size: 200KB
  • Format: WebP for web, PNG/JPG for mobile
  • Optimization: Always compress before adding
  • Examples: feature-search.png, feature-messaging.png
  • Tip: Consider lazy loading for below-the-fold images

Onboarding Images (images/onboarding/)

Section titled “Onboarding Images (images/onboarding/)”
  • Target size: < 100KB each
  • Format: WebP for web, PNG/JPG for mobile
  • Naming: Use sequential numbering for multi-step flows
  • Examples: onboarding-step-1.png, welcome.png

Avatars/Placeholders (images/avatars/)

Section titled “Avatars/Placeholders (images/avatars/)”
  • Target size: < 50KB each
  • Dimensions: Consistent sizes (e.g., 200x200)
  • Examples: default-avatar.png, placeholder-user.png

Miscellaneous (images/misc/)

Section titled “Miscellaneous (images/misc/)”
  • Images that don’t fit other categories
  • Use descriptive names

Icons (SVG)

Section titled “Icons (SVG)”
  • Viewbox: 24×24 or 16×16
  • Color: Use currentColor for fill/stroke
  • Optimization: Run through SVGO
  • Size: < 5KB each
  • Naming: kebab-case (arrow-right.svg)

Fonts

Section titled “Fonts”
  • Format: WOFF2 for web, TTF for mobile
  • Size: < 100KB per weight
  • Licensing: Ensure proper licensing
  • Recommendation: Use system fonts when possible

🚫 Anti-Patterns

Section titled “🚫 Anti-Patterns”

❌ Don’t: Brand Assets in Monorepo Package

Section titled “❌ Don’t: Brand Assets in Monorepo Package”
❌ packages/assets/images/pinkguest-hero.png
❌ packages/assets/images/orangeguest-hero.png


Problem: All brands bundle all images!

✅ Do: Brand Assets in Brand Directory

Section titled “✅ Do: Brand Assets in Brand Directory”
✅ apps/stay_match/pinkguest/shared/assets/images/hero-background.png
✅ apps/stay_match/orangeguest/shared/assets/images/hero-background.png


Benefit: Each brand only bundles its own images

❌ Don’t: Generic Icons in Brand Directory

Section titled “❌ Don’t: Generic Icons in Brand Directory”
❌ apps/stay_match/pinkguest/shared/assets/icons/arrow-right.svg


Problem: Duplicated across all brands!

✅ Do: Generic Icons in Monorepo Package

Section titled “✅ Do: Generic Icons in Monorepo Package”
✅ packages/assets/icons/arrows/arrow-right.svg


Benefit: Single source of truth, shared by all

📁 Directory Structure Reference

Section titled “📁 Directory Structure Reference”

Complete Structure:

Section titled “Complete Structure:”
monorepo/
├── packages/
│   └── assets/                              # Monorepo-wide
│       ├── icons/
│       │   ├── arrows/
│       │   ├── actions/
│       │   ├── navigation/
│       │   └── social/
│       ├── illustrations/
│       └── brand/
│           └── logo/
│
└── apps/
    └── {division}/
        └── {brand}/
            ├── web/
            │   └── src/                     # Uses shared assets
            ├── mobile/
            │   └── src/                     # Uses shared assets
            └── shared/                      # Brand-specific
                ├── assets/
                │   ├── images/
                │   └── fonts/
                ├── constants/
                │   └── content.ts
                └── config/
                    └── theme.ts

🔄 Asset Workflow

Section titled “🔄 Asset Workflow”

Adding Generic Asset:

Section titled “Adding Generic Asset:”
  1. Determine if truly generic (used by ALL divisions)
  2. Choose appropriate category (icons/illustrations/brand)
  3. Optimize asset (compress, remove metadata)
  4. Add to packages/assets/{category}/
  5. Update category README with asset details
  6. Import and use in any app

Adding Brand Asset:

Section titled “Adding Brand Asset:”
  1. Determine brand owner
  2. Optimize asset (compress, appropriate format)
  3. Add to apps/{division}/{brand}/shared/assets/{type}/
  4. Use relative imports in brand’s web/mobile apps
  5. Document in brand’s assets README

📚 Related Documentation

Section titled “📚 Related Documentation”

Key Principles

Section titled “Key Principles”
  1. Assets are brand-specific → each app has its own shared/assets/ folder

Last Updated: October 11, 2025
Maintained By: Engineering Team