Rustelo/book/developers/brand/logo-usage.md

# Logo Usage Guide

The Rustelo project includes a comprehensive logo system designed to work across different contexts and themes. This guide explains how to properly use the logos in your applications and documentation.

## Logo Assets

The logo system includes the following variants:

### Available Logo Files

| File | Usage | Context |
|------|-------|---------|
| `rustelo_dev-logo-h.svg` | Horizontal logo for normal/light themes | Primary horizontal logo |
| `rustelo_dev-logo-b-h.svg` | Horizontal logo for dark themes | Dark theme horizontal logo |
| `rustelo_dev-logo-v.svg` | Vertical logo for normal/light themes | Primary vertical logo |
| `rustelo_dev-logo-b-v.svg` | Vertical logo for dark themes | Dark theme vertical logo |
| `rustelo-imag.svg` | Logo image without text | Icon/favicon usage |

### Logo Locations

- **Source**: `logos/` directory (original assets)
- **Public**: `public/logos/` directory (web-accessible assets)
- **Documentation**: Referenced in mdBook via `../logos/` path

## Usage Guidelines

### 1. Web Application Usage

#### Navigation Logo
```rust
use crate::components::NavbarLogo;

// In your navigation component
view! {
    <nav class="navigation">
        <NavbarLogo size="small".to_string() />
        // ... other nav items
    </nav>
}
```

#### Brand Header
```rust
use crate::components::BrandHeader;

// For page headers
view! {
    <BrandHeader
        title="RUSTELO".to_string()
        subtitle="Modular Rust Web Application Template".to_string()
        logo_size="large".to_string()
        class="justify-center".to_string()
    />
}
```

#### Standalone Logo
```rust
use crate::components::Logo;

// Basic logo usage
view! {
    <Logo
        orientation="horizontal".to_string()
        size="medium".to_string()
        show_text={true}
        class="my-custom-class".to_string()
    />
}
```

### 2. Documentation Usage

#### Markdown Files
```markdown
<!-- In README.md or other markdown files -->
<div align="center">
  <img src="logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
  
  # Your Page Title
</div>
```

#### mdBook Pages
```markdown
<!-- In book pages -->
<div align="center">
  <img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="400" />
</div>

# Welcome to Rustelo
```

### 3. Size Guidelines

#### Component Sizes
- **small**: 32px height (navbar usage)
- **medium**: 48px height (standard usage)
- **large**: 64px height (headers)
- **xlarge**: 80px height (hero sections)

#### Documentation Sizes
- **Small**: 150-200px width
- **Medium**: 250-300px width
- **Large**: 350-400px width

### 4. Responsive Usage

The logo components automatically adapt to different screen sizes:

```rust
// Mobile-responsive logo
view! {
    <Logo
        orientation="horizontal".to_string()
        size="medium".to_string()
        show_text={true}
        class="w-full max-w-xs sm:max-w-sm md:max-w-md".to_string()
    />
}
```

## Theme Integration

### Automatic Theme Detection

The logo components automatically detect the current theme and switch between light and dark variants:

```rust
// This automatically uses the appropriate variant
view! {
    <Logo
        orientation="horizontal".to_string()
        size="medium".to_string()
        show_text={true}
    />
}
```

### Manual Theme Selection

For static contexts (like documentation), choose the appropriate variant:

- **Light backgrounds**: Use `rustelo_dev-logo-h.svg` or `rustelo_dev-logo-v.svg`
- **Dark backgrounds**: Use `rustelo_dev-logo-b-h.svg` or `rustelo_dev-logo-b-v.svg`

## Best Practices

### DO

✅ Use the horizontal logo for navigation bars and headers
✅ Use the vertical logo for sidebar or narrow layouts
✅ Use the image-only logo for favicons and small icons
✅ Maintain proper contrast with background colors
✅ Use consistent sizing within the same context
✅ Include proper alt text: "RUSTELO"

### DON'T

❌ Stretch or distort the logo proportions
❌ Use light logos on light backgrounds
❌ Use dark logos on dark backgrounds
❌ Make the logo too small to read (minimum 24px height)
❌ Use low-quality or pixelated versions

## Component API Reference

### Logo Component

```rust
#[component]
pub fn Logo(
    #[prop(default = "horizontal".to_string())] orientation: String,
    #[prop(default = "normal".to_string())] size: String,
    #[prop(default = true)] show_text: bool,
    #[prop(default = "".to_string())] class: String,
) -> impl IntoView
```

**Parameters:**
- `orientation`: "horizontal" | "vertical"
- `size`: "small" | "medium" | "large" | "xlarge"
- `show_text`: true (full logo) | false (image only)
- `class`: Additional CSS classes

### LogoLink Component

```rust
#[component]
pub fn LogoLink(
    #[prop(default = "horizontal".to_string())] orientation: String,
    #[prop(default = "normal".to_string())] size: String,
    #[prop(default = true)] show_text: bool,
    #[prop(default = "".to_string())] class: String,
    #[prop(default = "/".to_string())] href: String,
) -> impl IntoView
```

**Additional Parameters:**
- `href`: Link destination (default: "/")

### BrandHeader Component

```rust
#[component]
pub fn BrandHeader(
    #[prop(default = "RUSTELO".to_string())] title: String,
    #[prop(default = "".to_string())] subtitle: String,
    #[prop(default = "medium".to_string())] logo_size: String,
    #[prop(default = "".to_string())] class: String,
) -> impl IntoView
```

**Parameters:**
- `title`: Main brand title
- `subtitle`: Optional subtitle text
- `logo_size`: Logo size variant
- `class`: Additional CSS classes

### NavbarLogo Component

```rust
#[component]
pub fn NavbarLogo(
    #[prop(default = "small".to_string())] size: String,
    #[prop(default = "".to_string())] class: String,
) -> impl IntoView
```

**Parameters:**
- `size`: Logo size (optimized for navbar)
- `class`: Additional CSS classes

## Usage Examples

### Hero Section
```rust
view! {
    <section class="hero">
        <BrandHeader
            title="RUSTELO".to_string()
            subtitle="Build fast, secure web applications with Rust".to_string()
            logo_size="xlarge".to_string()
            class="text-center".to_string()
        />
    </section>
}
```

### Sidebar
```rust
view! {
    <aside class="sidebar">
        <Logo
            orientation="vertical".to_string()
            size="medium".to_string()
            show_text={true}
            class="mb-4".to_string()
        />
    </aside>
}
```

### Footer
```rust
view! {
    <footer class="footer">
        <Logo
            orientation="horizontal".to_string()
            size="small".to_string()
            show_text={false}
            class="opacity-60".to_string()
        />
    </footer>
}
```

## Troubleshooting

### Logo Not Displaying

1. **Check file paths**: Ensure logos are copied to `public/logos/`
2. **Verify imports**: Make sure components are properly imported
3. **Theme detection**: Confirm theme context is available

### Theme Switching Issues

1. **Theme provider**: Ensure `ThemeProvider` is properly configured
2. **CSS classes**: Check that theme-specific CSS is loaded
3. **JavaScript**: Verify theme switching JavaScript is working

### Performance Optimization

1. **SVG optimization**: Use optimized SVG files
2. **Lazy loading**: Add `loading="lazy"` for non-critical logos
3. **Caching**: Ensure proper cache headers for logo assets

## File Structure

```
template/
├── logos/                     # Source logo files
│   ├── rustelo_dev-logo-h.svg
│   ├── rustelo_dev-logo-b-h.svg
│   ├── rustelo_dev-logo-v.svg
│   ├── rustelo_dev-logo-b-v.svg
│   └── rustelo-imag.svg
├── public/
│   └── logos/                 # Web-accessible logo files
│       ├── rustelo_dev-logo-h.svg
│       ├── rustelo_dev-logo-b-h.svg
│       ├── rustelo_dev-logo-v.svg
│       ├── rustelo_dev-logo-b-v.svg
│       └── rustelo-imag.svg
└── client/src/components/
    └── Logo.rs                # Logo components
```

## Contributing

When adding new logo variants or updating existing ones:

1. Update both `logos/` and `public/logos/` directories
2. Test with both light and dark themes
3. Verify responsive behavior
4. Update this documentation
5. Test in all supported browsers

For questions or issues with logo usage, please refer to the [GitHub Issues](https://github.com/yourusername/rustelo/issues) page.