# Diagrams & Visuals / Sơ Đồ & Hình Ảnh

This reference provides detailed guidelines for creating and managing visual content in documentation.

## When to Use Diagrams

| Diagram Type | Use Case | Mermaid Type |
|--------------|----------|--------------|
| **Architecture** | High-level system overview, service dependencies | `graph TB` |
| **Sequence** | Request/response flows, async processes, integrations | `sequenceDiagram` |
| **ER Diagram** | Database schema, table relationships | `erDiagram` |
| **State** | Status transitions (Order, Campaign, Payment) | `stateDiagram-v2` |
| **Class** | Domain model, entity relationships | `classDiagram` |
| **Flowchart** | Decision trees, business logic flows | `flowchart TD` |

## Mermaid Dark Palette (MANDATORY)

**CRITICAL**: Always use the dark color palette from [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md).

**Standard Colors:**
- **Primary (Blue)**: `#3498DB` - Main components, API layer
- **Secondary (Purple)**: `#8E44AD` - Application layer, handlers
- **Accent (Orange)**: `#E67E22` - Domain layer, business logic
- **Neutral (Dark Gray)**: `#34495E` - Databases, infrastructure
- **Success (Green)**: `#27AE60` - Success states
- **Warning (Yellow)**: `#F39C12` - Warning states
- **Danger (Red)**: `#E74C3C` - Error states

**Example:**
```mermaid
graph TB
    API[API Layer]
    APP[Application]
    DOMAIN[Domain]
    DB[(Database)]
    
    API --> APP
    APP --> DOMAIN
    APP --> DB
    
    style API fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98
    style APP fill:#3498DB,color:#ECF0F1,stroke:#2980B9
    style DOMAIN fill:#E67E22,color:#ECF0F1,stroke:#D35400
    style DB fill:#34495E,color:#ECF0F1,stroke:#2C3E50
```

## Screenshot Guidelines

### File Naming

- ✅ Descriptive: `auth-flow-login-screen.png`
- ❌ Generic: `screenshot1.png`, `image.png`

### File Organization

```
docs/
├── en/
│   ├── images/
│   │   ├── architecture/
│   │   ├── screenshots/
│   │   └── diagrams/
│   └── README.md
└── vi/
    ├── images/          # Mirror EN structure
    └── README.md
```

### File Format

- **PNG**: UI screenshots, diagrams with transparency
- **JPG**: Photos, images without transparency
- **SVG**: Vector graphics, logos (when possible)
- **WebP**: Modern format for smaller file sizes

### Optimization

```bash
# Optimize PNG files
pngquant --quality 65-80 docs/en/images/*.png

# Optimize JPG files
jpegoptim --max=85 docs/en/images/*.jpg

# Convert to WebP
cwebp -q 80 input.png -o output.webp
```

### Embedding in Markdown

```markdown
# ✅ GOOD: With descriptive caption and alt text
![Login flow showing email input, password field, and social login options](images/auth-flow-login.png)

# ❌ BAD: No context
![Screenshot](screenshot.png)
```

### Responsive Images

```markdown
<img src="images/large-diagram.png" alt="System Architecture" width="800">
```

## Resources

- [Mermaid Diagrams Skill](../mermaid-diagrams/SKILL.md) - MANDATORY for all diagrams
- [Mermaid Live Editor](https://mermaid.live/) - Test Mermaid diagrams
- [Back to Documentation Skill](../SKILL.md)