title: "Lesson 5: Views & Styling"
weight: 5
summary: "Focus diagrams with views; improve legibility with styling."
---

# Lesson 5: Views & Styling

## The Traffic Light Principle

Think about traffic lights. They use three colors with specific meanings:

- **Red** = Stop, danger, critical
- **Yellow** = Caution, warning
- **Green** = Go, safe, normal

You don't need a legend. You don't need to think. You instantly understand.

Good architecture styling works the same way. It uses visual elements to communicate meaning, not to look pretty.

## Why Styling Matters

Your brain processes visual information in two ways:

1. **Fast thinking (System 1)** - Instant pattern recognition, gut reactions
2. **Slow thinking (System 2)** - Deliberate analysis, reading labels

Good styling triggers System 1. Before you even read the labels, you should understand:
- What's important (visual weight)
- How things connect (line styles)
- What things are (shapes and colors)
- Where to look first (hierarchy)

Let me show you the difference.

### Before: The Uniform Diagram

```sruja
// partial
import { * } from 'sruja.ai/stdlib'

// Everything looks the same. No visual hierarchy.
Customer = person "Customer"

Shop = system "E-Commerce Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  DB = database "Database"
}

Customer -> Shop.WebApp "Uses"
Shop.WebApp -> Shop.API "Calls"
Shop.API -> Shop.DB "Reads/Writes"

view index {
  title "Everything Looks the Same"
  include *
}
```

Everything has equal visual weight. Your eye doesn't know where to go. You have to read every label to understand what's happening.

### After: Styled with Purpose

```sruja
// partial
import { * } from 'sruja.ai/stdlib'

Customer = person "Customer"

Shop = system "E-Commerce Shop" {
  WebApp = container "Web Application"
  API = container "API Service"
  DB = database "Database"
}

Customer -> Shop.WebApp "Uses"
Shop.WebApp -> Shop.API "Calls"
Shop.API -> Shop.DB "Reads/Writes"

// Global styles apply to all views
style {
  // Databases are always cylinders in green
  element "Database" {
    shape cylinder
    color "#10b981"  // Green - stable, persistent
  }
  
  // Read operations in blue (cool, safe)
  relation "Reads/Writes" {
    color "#3b82f6"
  }
}

view index {
  title "Styled with Purpose"
  include *
}
```

Now, before you read anything, you already know:
- That cylinder thing is a database (shape)
- The database is stable/persistent (green color)
- Data flows to/from it (blue line)

## Sruja Styling: The Basics

Sruja gives you two levels of styling:

### 1. Global Styles

Apply to all views. Use for consistent element types:

```sruja
// partial
// Define once, apply everywhere
style {
  element "Database" {
    shape cylinder
    color "#22c55e"
  }
  
  element "Cache" {
    shape cylinder
    color "#f59e0b"  // Orange = fast, temporary
  }
  
  relation "Processes payments" {
    color "#ef4444"  // Red = critical path
    thickness 3
  }
}
```

### 2. View-Specific Styles

Apply to one view. Use to highlight what matters in that context:

```sruja
// partial
view security {
  title "Security View"
  include PaymentGateway Shop.API Shop.DB
  
  // Only in this view: highlight security concerns
  style {
    element "API" {
      color "#ef4444"  // Red = security focus
    }
    
    relation "Processes payments" {
      style dashed  // Dashed = needs review
    }
  }
}
```

View-specific styles override global styles. This lets you maintain consistency while highlighting what matters for each audience.

## Complete Example: E-Commerce with Purposeful Styling

Let me show you a real-world example with intentional styling:

```sruja
// partial
import { * } from 'sruja.ai/stdlib'

Customer = person "Customer"

ECommerce = system "E-Commerce System" {
  WebApp = container "Web Application"
  API = container "API Service"
  OrderDB = database "Order Database"
  ProductDB = database "Product Database"
}

Customer -> ECommerce.WebApp "Browses"
ECommerce.WebApp -> ECommerce.API "Fetches data"
ECommerce.API -> ECommerce.OrderDB "Stores orders"
ECommerce.API -> ECommerce.ProductDB "Queries products"

// Global styles: Consistent visual language
style {
  // All databases look the same
  element "Database" {
    shape cylinder
    color "#22c55e"  // Green = stable, persistent
  }
  
  // Data retrieval = blue (cool, safe)
  relation "Fetches data" {
    color "#3b82f6"
  }
  
  // Data storage = orange (warm, action)
  relation "Stores orders" {
    color "#f59e0b"
    thickness 2
  }
  
  // Read operations = thinner
  relation "Queries products" {
    color "#3b82f6"
    thickness 1
  }
}

// Complete view with all styling
view index {
  title "Complete System View"
  include *
}

// Data flow view with custom emphasis
view dataflow {
  title "Data Flow View"
  include ECommerce.API
  include ECommerce.OrderDB
  include ECommerce.ProductDB
  exclude Customer
  exclude ECommerce.WebApp
  
  // Override global styles for this view
  style {
    element "API" {
      color "#0ea5e9"  // Blue = data orchestrator
      thickness 3
    }
    
    // Emphasize write operations
    relation "Stores orders" {
      color "#ef4444"  // Red = critical writes
      thickness 3
    }
  }
}
```

### What This Styling Communicates

Without reading a single label, the styling tells you:

- **Green cylinders** = Databases (stable, persistent storage)
- **Blue lines** = Read operations (safe, idempotent)
- **Orange/red lines** = Write operations (changes state, be careful)
- **Thick lines** = Critical paths (important, frequent)
- **Thin lines** = Secondary paths (less critical)

## Real-World Case Studies

### AWS: Color Coding by Service Type

AWS architecture diagrams use consistent colors:

- **Orange** = Compute (EC2, Lambda)
- **Blue** = Storage (S3, EBS)
- **Green** = Database (RDS, DynamoDB)
- **Purple** = Analytics (Redshift, Athena)

This consistency means AWS architects can look at any AWS diagram and instantly understand the service mix. No legend needed.

### GitHub: Minimal but Meaningful

GitHub's internal architecture docs use minimal styling:

- **Gray** = Existing services
- **Blue** = New services (in a proposal)
- **Red borders** = Deprecated services

Three colors. Clear meaning. Zero confusion.

### Spotify: Styling for Scale

Spotify's architecture diagrams use visual weight to show scale:

- **Large boxes** = Major services (100+ instances)
- **Medium boxes** = Standard services (10-100 instances)
- **Small boxes** = Small services (<10 instances)
- **Dashed borders** = External dependencies

Size communicates scale. Style communicates meaning.

## When to Style (Framework)

Here's my framework for deciding when to apply styling:

### Always Style

**1. Element Types**
- Databases should look different from services
- External systems should look different from internal ones
- Use consistent shapes and colors for each type

**2. Critical Relationships**
- Payment flows
- Security boundaries
- Data pipelines
- Anything that, if broken, causes major issues

**3. State Changes**
- Read vs. write operations
- Sync vs. async communication
- Permanent vs. temporary data

### Sometimes Style

**4. Performance Indicators**
- Hot paths (frequently used)
- Bottlenecks
- Cached vs. uncached data

**5. Ownership Boundaries**
- Team A's services
- Team B's services
- Shared infrastructure

### Rarely Style

**6. Technology Stack**
- Java vs. Python services
- PostgreSQL vs. MySQL databases
- This is usually noise, not signal

**7. Version Information**
- v1 vs. v2 services
- Deprecated systems (use red border, but don't overdo it)

## Common Styling Mistakes

### Mistake #1: The Rainbow Diagram

**What happens:** You use 10+ colors because "they all have meaning."

**Why it fails:**
- No one can remember 10 color meanings
- Visual overload
- Looks unprofessional

**The fix:** Limit to 3-5 colors with clear, distinct meanings. If you need more, use shapes or line styles instead.

### Mistake #2: No Visual Hierarchy

**What happens:** Everything is equally bold, equally colorful, equally large.

**Why it fails:**
- Viewer doesn't know where to look first
- Critical paths get lost in the noise
- Feels overwhelming

**The fix:** Make important things visually prominent. Use size, color intensity, and thickness to create hierarchy.

### Mistake #3: Inconsistent Meaning

**What happens:** Blue means "database" in one diagram and "external service" in another.

**Why it fails:**
- Confuses people who see multiple diagrams
- Undermines trust in documentation
- Requires constant legend-checking

**The fix:** Create a style guide and stick to it across all diagrams.

### Mistake #4: Style Over Substance

**What happens:** Beautiful diagrams that don't communicate clearly.

**Why it fails:**
- Form over function
- People admire the diagram but don't understand the architecture
- Time wasted on decoration

**The fix:** Before adding any style, ask: "Does this help the viewer understand faster?" If no, remove it.

### Mistake #5: Ignoring Accessibility

**What happens:** Red/green color coding that's invisible to colorblind viewers.

**Why it fails:**
- 8% of men have some color blindness
- Excludes part of your audience
- May fail accessibility requirements

**The fix:**
- Don't rely on color alone (use shapes, patterns, labels too)
- Test with color blindness simulators
- Use colorblind-friendly palettes (blue/orange instead of red/green)

## The STYLE Framework

When styling your diagrams, use this framework:

**S - Semantic Meaning**
- Every style choice should communicate something
- If you can't explain why, remove it

**T - Type Differentiation**
- Different element types should look different
- Databases ≠ Services ≠ External Systems

**Y - Yield Hierarchy**
- Important things should be visually prominent
- Critical paths should stand out

**L - Limit Colors**
- Maximum 5 colors with distinct meanings
- Use shapes and line styles for additional differentiation

**E - Ensure Consistency**
- Same element type = same style across all diagrams
- Create and follow a style guide

## Practical Exercise

Take the e-commerce example above and create a new styled view:

**Challenge:** Create a "Performance View" that shows:
- Database query hot paths (thick lines)
- Cacheable vs. non-cacheable data (dashed vs. solid)
- Critical user journey (highlighted)

**Hint:** Use view-specific styles to override global styles for performance concerns.

## What to Remember

1. **Styling is communication, not decoration** - Every style choice should convey meaning
2. **Limit your palette** - 3-5 colors max, each with distinct meaning
3. **Create visual hierarchy** - Important things should look important
4. **Be consistent** - Same element type = same style across all diagrams
5. **Test accessibility** - Don't rely on color alone; consider color blindness
6. **Global styles for consistency, view styles for emphasis** - Define element types globally, highlight specifics per view
7. **When in doubt, simplify** - Remove styling that doesn't clarify

## When to Skip Styling

Sometimes, plain is better:

- **Early exploration** - When you're still figuring out the architecture, don't waste time on styling
- **Internal discussions** - If only architects see it and they know the system, minimal styling is fine
- **Simple systems** - 3 boxes don't need color coding
- **Rapid prototyping** - Get the structure right first, style later

Style when you need to communicate. Skip it when you're just thinking through problems.

---

**Next up:** We'll explore how to model complex real-world systems with all the techniques we've learned.
