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.

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:

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

# 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

# ✅ 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

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

Resources

Mermaid Diagrams Skill - MANDATORY for all diagrams
Mermaid Live Editor - Test Mermaid diagrams
Back to Documentation Skill

3.1 KiB Raw Blame History