Diagram Styling System 2: Color + Border Hybrid
This document defines the System 2 (Color + Border Hybrid) styling system for all Mermaid diagrams in the project. This system integrates both the color scheme from DIAGRAM_COLOR_STANDARD.md and border styling rules.
Core Foundation: State vs Function Separation
The system follows the State vs Function Separation principle from DIAGRAM_COLOR_STANDARD.md:
- Fill color = State (data quality: Bronze/Silver/Gold/Quarantine)
- Border color = Function (component type: ETL, Infrastructure, CI/CD, etc.)
Key Rule: For state nodes (Bronze/Silver/Gold), the border color represents the function/context (ETL processing, infrastructure, CI/CD), not the state itself.
Philosophy
Color + Border Hybrid (Balanced Approach): Colors remain primary for semantic meaning. Borders enhance only where needed (conflicts, emphasis, hierarchy). This system balances visual clarity with subtlety.
Core Principles
- Colors are primary - State vs Function separation drives semantic meaning
- Borders solve conflicts - Use borders to distinguish same-color tokens
- Borders add emphasis - Thick borders for important/special concepts
- Selective application - Not every node needs a border
- State vs Function separation - Fill = state, Border = function (when border needed)
Complete Node Styling Rules
| Category | Token | Fill Color | Border Color | Border Style | Width | Pattern | When to Use | Mermaid Syntax Example |
|---|---|---|---|---|---|---|---|---|
| State: Bronze | state.bronze | Orange #f57c00 | Function (ETL: #7b1fa2, Infra: #424242) | Solid | 2px | - | Only when function border needed (ETL processing) | fill:#f57c00,stroke:#7b1fa2,stroke-width:2px,color:#fff (ETL context) |
| State: Silver | state.silver | Green #388e3c | Function (ETL: #7b1fa2, Infra: #424242) | Solid | 2px | - | Only when function border needed (ETL processing) | fill:#388e3c,stroke:#7b1fa2,stroke-width:2px,color:#fff (ETL context) |
| State: Gold | state.gold | Blue #1976d2 | Function (ETL: #7b1fa2, Infra: #424242) | Solid | 2px | - | Only when function border needed (ETL processing) | fill:#1976d2,stroke:#7b1fa2,stroke-width:2px,color:#fff (ETL context) |
| State: Quarantine | state.quarantine | Red #d32f2f | Match fill (red) | Solid | 2px | - | Always (for emphasis) | fill:#d32f2f,stroke:#d32f2f,stroke-width:2px,color:#fff |
| Function: ETL | func.etl | Light Purple #ba68c8 | None | None | - | - | Usually no border | fill:#ba68c8,color:#111 (no border) |
| Function: ETL Light | func.etl.light | Light Purple #ba68c8 | Match fill | Dotted | 2px | 2 2 | Always - distinguishes from control | fill:#ba68c8,stroke:#ba68c8,stroke-width:2px,stroke-dasharray: 2 2,color:#111 |
| Function: Infrastructure | func.infra | Dark Gray #424242 | Match fill | Solid | 1px | - | Optional - subtle if needed | fill:#424242,stroke:#424242,stroke-width:1px,color:#fff (optional) |
| Control: Decision | control.decision | Yellow #fbc02d | Match fill | Dashed | 2px | 5 5 | Always - distinguishes from state nodes | fill:#fbc02d,stroke:#fbc02d,stroke-width:2px,stroke-dasharray: 5 5,color:#111 |
| Control: Testing | control.testing | Light Green #66bb6a | Match fill | Dashed | 2px | 5 5 | Always - distinguishes from state.silver.light | fill:#66bb6a,stroke:#66bb6a,stroke-width:2px,stroke-dasharray: 5 5,color:#111 |
| Control: CI/CD | control.cicd | Indigo #5c6bc0 | Match fill | Solid | 2px | - | Always (for emphasis) | fill:#5c6bc0,stroke:#5c6bc0,stroke-width:2px,color:#fff |
| State Light: Bronze | state.bronze.light | Light Orange #ffb74d | Function or Match fill | Dotted | 2px | 2 2 | Always - distinguishes from control nodes | fill:#ffb74d,stroke:#7b1fa2,stroke-width:2px,stroke-dasharray: 2 2,color:#111 |
| State Light: Silver | state.silver.light | Light Green #66bb6a | Function or Match fill | Dotted | 2px | 2 2 | Always - distinguishes from control nodes | fill:#66bb6a,stroke:#7b1fa2,stroke-width:2px,stroke-dasharray: 2 2,color:#111 |
| State Light: Gold | state.gold.light | Light Blue #64b5f6 | Function or Match fill | Dotted | 2px | 2 2 | Always - distinguishes from control nodes | fill:#64b5f6,stroke:#7b1fa2,stroke-width:2px,stroke-dasharray: 2 2,color:#111 |
| Meta: Security | meta.security | Deep Purple #6a1b9a | Match fill | Solid | 3px | - | Always - special emphasis | fill:#6a1b9a,stroke:#6a1b9a,stroke-width:3px,color:#fff |
| Meta: Observability | meta.observability | Teal #00897b | Match fill | Solid | 3px | - | Always - special emphasis | fill:#00897b,stroke:#00897b,stroke-width:3px,color:#fff |
| Status: Success | status.success | Dark Green #2e7d32 | None | None | - | - | Usually no border (fill is enough) | fill:#2e7d32,color:#fff (no border) |
| Status: Warning | status.warning | Amber #ffa000 | Match fill | Solid | 2px | - | Optional - only if needed for clarity | fill:#ffa000,stroke:#ffa000,stroke-width:2px,color:#111 |
| Status: Error | status.error | Red #d32f2f | Match fill | Solid | 3px | - | Always - critical emphasis | fill:#d32f2f,stroke:#d32f2f,stroke-width:3px,color:#fff |
Edge Styling Rules
| Flow Type | Token | Color | Style | Width | Pattern | When to Use | Mermaid Syntax |
|---|---|---|---|---|---|---|---|
| Normal Data Flow | flow.processing | Purple #7b1fa2 | Solid | 2px | - | Default - most connections | stroke:#7b1fa2,stroke-width:2px |
| Conditional Flow | flow.output | Teal #00897b | Dashed | 2px | 5 5 | If/else paths, optional paths | stroke:#00897b,stroke-width:2px,stroke-dasharray: 5 5 |
| Input Flow | flow.input | Light Blue #64b5f6 | Solid | 2px | - | Data input, external source | stroke:#64b5f6,stroke-width:2px |
| I/O Flow | flow.io | Cyan #00acc1 | Dotted | 1px | 2 2 | Observability, lineage (non-data) | stroke:#00acc1,stroke-width:1px,stroke-dasharray: 2 2 |
| Error/Quarantine Flow | status.error | Red #d32f2f | Dashed | 3px | 8 4 | Error/quarantine paths | stroke:#d32f2f,stroke-width:3px,stroke-dasharray: 8 4 |
| Observability Flow | meta.observability | Teal #00897b | Dotted | 2px | 3 3 | Monitoring, metrics (non-data) | stroke:#00897b,stroke-width:2px,stroke-dasharray: 3 3 |
Key Distinction Rules
Color Conflict Resolution
Same color, different meaning:
control.testing(#66bb6a) → Dashed borderstroke-dasharray: 5 5(control context)state.silver.light(#66bb6a) → Dotted borderstroke-dasharray: 2 2(state sub-variant context)- Result: Same color, different border = clear distinction
Border Application Rules
-
Always use borders for:
- Control nodes (decision, testing) - dashed (2px)
- Light variants - dotted (2px)
- Meta tokens - thick (3px)
- Errors - thick (3px)
-
Optional borders for:
- State nodes - only if function border needed (ETL processing context)
- Normal flows - default solid
- Infrastructure - subtle (1px) if needed
-
No borders for:
- ETL processing nodes (fill is enough)
- Success states (fill is enough)
- Simple flows (default solid)
Complete Example
Key Features:
- Moderate borders (2px) - not overwhelming
- State nodes: Fill = state color, Border = function color (when needed)
- Dashed borders for control nodes (always)
- Dotted borders for light variants (always)
- Thick borders (3px) only for meta tokens and errors
- Selective application - borders only where neededdocusaur
- Clear distinction:
control.testing(dashed) vsstate.silver.light(dotted with function border)
Implementation Checklist
- Control nodes (Decision/Testing): Always add
stroke-width:2px,stroke-dasharray: 5 5dashed border matching fill - Light variants: Always add
stroke-width:2px,stroke-dasharray: 2 2dotted border (function color or match fill) - Meta tokens: Always add
stroke-width:3pxthick solid border matching fill - Errors: Always add
stroke-width:3pxthick solid border matching fill - State nodes: Add
stroke-width:2pxborder with function color only if function border needed (ETL processing) - Normal edges: Use flow token colors (default solid, 2px)
- Conditional edges: Use dashed
stroke-dasharray: 5 5 - Metadata edges: Use dotted
stroke-dasharray: 2 2
Mermaid Syntax Reference
Border Styling Syntax
Edge Styling Syntax
Quick Reference
Node Borders
State Nodes: 2px solid (function color, if needed)
Control Nodes: 2px dashed (match fill) - ALWAYS
Light Variants: 2px dotted (function or match fill) - ALWAYS
Meta Tokens: 3px solid (match fill) - ALWAYS
Errors: 3px solid (match fill) - ALWAYS
Quarantine: 2px solid (match fill) - ALWAYS
Edge Styling
Normal Flow: 2px solid (flow color)
Conditional: 2px dashed (flow color)
Metadata: 1px dotted (flow color)
Error: 3px dashed (error color)
Extended Styling Rules for New Diagram Types
Timeline Diagrams
Styling Approach: Timeline diagrams use default Mermaid styling. No custom styling needed.
Color Guidelines:
- Timeline entries inherit default Mermaid colors
- Use descriptive labels that indicate state/function when relevant
- Milestones can be emphasized with descriptive text
Example:
Note: Timeline diagrams don't support custom styling in Mermaid. Use descriptive text to convey meaning.
State Diagrams
Styling Approach: Apply state colors to state nodes, function colors to transitions.
State Node Styling:
- Bronze state:
fill:#f57c00,color:#fff - Silver state:
fill:#388e3c,color:#fff - Gold state:
fill:#1976d2,color:#fff - Quarantine state:
fill:#d32f2f,stroke:#d32f2f,stroke-width:2px,color:#fff - Condemned state:
fill:#d32f2f,stroke:#d32f2f,stroke-width:3px,color:#fff
Transition Styling:
- Normal transitions: Default (black)
- Error transitions:
stroke:#d32f2f,stroke-width:2px - Success transitions:
stroke:#2e7d32,stroke-width:2px
Example:
Sankey Diagrams / Flowchart Alternatives
Styling Approach: Use state colors for data layers, function colors for processing nodes.
Node Styling:
- Bronze/Source nodes:
fill:#f57c00,color:#fff - Silver nodes:
fill:#388e3c,stroke:#7b1fa2,stroke-width:2px,color:#fff - Gold nodes:
fill:#1976d2,stroke:#7b1fa2,stroke-width:2px,color:#fff - Quarantine nodes:
fill:#d32f2f,stroke:#d32f2f,stroke-width:2px,color:#fff - Processing nodes:
fill:#ba68c8,color:#111
Edge Styling:
- Normal flow:
stroke:#7b1fa2,stroke-width:2px - Error flow:
stroke:#d32f2f,stroke-width:3px,stroke-dasharray: 8 4 - Success flow:
stroke:#2e7d32,stroke-width:2px
Note: Since sankey-beta is experimental, use flowchart alternatives with volume labels.
Pie Charts
Styling Approach: Use function/state colors matching the data categories.
Color Mapping:
- ETL/Processing costs: Purple
#ba68c8 - Storage costs: Gray
#424242 - Query costs: Light Blue
#64b5f6 - Infrastructure costs: Indigo
#5c6bc0 - Data quality categories: Use state colors (Bronze/Silver/Gold/Quarantine)
Example:
Note: Pie charts use default Mermaid colors. Use descriptive labels that reference our color scheme.
User Journey Diagrams
Styling Approach: Use function colors for different journey stages.
Stage Colors:
- Discovery: Blue
#1976d2(Gold-like, authoritative) - Development: Purple
#ba68c8(ETL-like, active) - Deployment: Indigo
#5c6bc0(CI/CD-like) - Operations: Green
#388e3c(Silver-like, validated)
Example:
Note: User journey diagrams use default Mermaid styling. Use descriptive section names.
Entity Relationship Diagrams
Styling Approach: Use state colors for entity types, function colors for relationships.
Entity Styling:
- Transaction entities: Orange
#f57c00(Bronze-like, raw data) - Validated entities: Green
#388e3c(Silver-like) - Aggregated entities: Blue
#1976d2(Gold-like) - Error entities: Red
#d32f2f(Quarantine-like)
Relationship Styling:
- Normal relationships: Default (black)
- Error relationships:
stroke:#d32f2f,stroke-width:2px
Example:
Note: ER diagrams have limited styling support. Use entity names and descriptions to convey meaning.
Quadrant Charts
Styling Approach: Use status colors for different quadrants.
Quadrant Colors (via labels):
- High Impact/High Probability: Red
#d32f2f(Mitigate) - High Impact/Low Probability: Amber
#ffa000(Monitor) - Low Impact/High Probability: Yellow
#fbc02d(Accept) - Low Impact/Low Probability: Green
#2e7d32(Accept)
Example:
Note: Quadrant charts use default Mermaid colors. Use descriptive quadrant labels.
C4 Diagrams
Styling Approach: Use function colors for system types.
System Colors:
- Person: Default (no custom styling)
- System (ETL): Purple
#ba68c8 - System (Storage): Gray
#424242 - System (Reporting): Blue
#1976d2 - System (Monitoring): Teal
#00897b
Relationship Styling:
- Data flow:
stroke:#7b1fa2,stroke-width:2px - Control flow:
stroke:#5c6bc0,stroke-width:2px - Observability:
stroke:#00897b,stroke-width:2px,stroke-dasharray: 3 3
Example:
Note: C4 diagrams have limited styling. Use system descriptions to convey meaning.
Mindmaps
Styling Approach: Use state/function colors for different branches.
Branch Colors:
- Architecture branches: Blue
#1976d2(Gold-like) - ETL branches: Purple
#ba68c8(ETL-like) - Infrastructure branches: Gray
#424242 - Governance branches: Indigo
#5c6bc0(CI/CD-like) - Monitoring branches: Teal
#00897b(Observability)
Example:
Note: Mindmaps use default Mermaid colors. Use descriptive branch names that reference our color scheme.
Sequence Diagrams
Styling Approach: Use function colors for participant types.
Participant Colors:
- ETL/Processing: Purple
#ba68c8 - Storage: Gray
#424242 - Monitoring: Teal
#00897b - Infrastructure: Indigo
#5c6bc0 - Human: Default (no custom styling)
Message Styling:
- Data flow:
stroke:#7b1fa2,stroke-width:2px - Error messages:
stroke:#d32f2f,stroke-width:3px,stroke-dasharray: 8 4 - Observability:
stroke:#00897b,stroke-width:2px,stroke-dasharray: 3 3
Example:
Note: Sequence diagrams have limited styling. Use participant names and message labels to convey meaning.
Class Diagrams
Styling Approach: Use state colors for data classes, function colors for processing classes.
Class Colors:
- Data classes (Bronze): Orange
#f57c00 - Data classes (Silver): Green
#388e3c - Data classes (Gold): Blue
#1976d2 - Processing classes: Purple
#ba68c8 - Error classes: Red
#d32f2f
Relationship Styling:
- Normal relationships: Default (black)
- Error relationships:
stroke:#d32f2f,stroke-width:2px
Example:
Note: Class diagrams have limited styling. Use class names and descriptions to convey meaning.
XY Charts
Styling Approach: Use function colors for different data series.
Series Colors:
- Performance metrics: Purple
#7b1fa2 - Cost metrics: Gray
#424242 - Quality metrics: Green
#388e3c - Error metrics: Red
#d32f2f
Example:
Note: XY charts use default Mermaid colors. Use descriptive titles and axis labels.
Block Diagrams
Styling Approach: Use state/function colors for different block groups.
Block Colors:
- Storage blocks: Use state colors (Bronze/Silver/Gold/Quarantine)
- Processing blocks: Purple
#ba68c8 - Infrastructure blocks: Gray
#424242 - Monitoring blocks: Teal
#00897b
Example:
Note: Block diagrams have limited styling. Use descriptive block labels.
Requirement Diagrams
Styling Approach: Use status colors for requirement risk levels.
Requirement Colors (via risk levels):
- High risk: Red
#d32f2f - Medium risk: Amber
#ffa000 - Low risk: Green
#2e7d32
Example:
Note: Requirement diagrams use default Mermaid styling. Use risk levels to convey importance.
Summary: Styling by Diagram Type
| Diagram Type | Styling Support | Primary Colors | Notes |
|---|---|---|---|
| Timeline | None | Default | Use descriptive text |
| State | Full | State colors | Apply state colors to nodes |
| Sankey | Limited | State/Function colors | Use flowchart alternative |
| Pie Chart | Limited | Function colors | Use descriptive labels |
| User Journey | None | Default | Use descriptive sections |
| ER Diagram | Limited | State colors | Use entity names |
| Quadrant | Limited | Status colors | Use quadrant labels |
| C4 | Limited | Function colors | Use system descriptions |
| Mindmap | Limited | State/Function colors | Use branch names |
| Sequence | Limited | Function colors | Use participant names |
| Class | Limited | State/Function colors | Use class names |
| XY Chart | Limited | Function colors | Use descriptive titles |
| Block | Limited | State/Function colors | Use block labels |
| Requirement | Limited | Status colors | Use risk levels |
General Rule: When custom styling is limited, use descriptive names, labels, and text that reference our color scheme to maintain consistency.
See Also
- Diagram Color Standard - Complete color token definitions
- README - Documentation overview with diagram legend
- Visual Enhancement Plan - New diagram types and examples