Diagram Color Standard (Enhanced)

This document defines the enhanced, systematic color scheme for all Mermaid diagrams in the project. The schema uses a State vs Function separation model to reduce ambiguity and improve accessibility.

Core Principle: State vs Function Separation

Rule: Use fill color for State (data quality), use border/edge color for Function (component/action type)

State colors = "What quality/state is this data in?" (Bronze/Silver/Gold/Quarantine)
Function colors = "What kind of component/action is this?" (ETL, Infrastructure, CI/CD, etc.)

1. State Tokens (Data Quality/State)

Token	Color	Hex	Text	Semantic Meaning	Usage
`state.bronze`	Orange	`#f57c00`	`#fff`	Raw, unvalidated, untrusted data	Bronze layer nodes
`state.bronze.light`	Light Orange	`#ffb74d`	`#111`	Bronze sub-states (experimental, staging)	Bronze variants with dotted border
`state.silver`	Green	`#388e3c`	`#fff`	Validated, quality-assured data	Silver layer nodes
`state.silver.light`	Light Green	`#66bb6a`	`#111`	Silver sub-states (validated+joined, validated+anonymized)	Silver variants
`state.silver.restricted`	Green	`#388e3c`	`#fff`	Silver with PII/sensitive data	Same color + 🔒 icon in label
`state.gold`	Blue	`#1976d2`	`#fff`	Authoritative, business-ready data	Gold layer nodes
`state.gold.light`	Light Blue	`#64b5f6`	`#111`	Gold sub-states (experimental views)	Gold variants
`state.quarantine`	Red	`#d32f2f`	`#fff`	Invalid data, pipeline stops/diverts	Quarantine layer nodes

State Semantics Contract:

Bronze: Data exists but not validated; pipeline must process before use
Silver: Data validated and quality-assured; safe for analytics
Gold: Data is authoritative business contract; production-ready for reporting
Quarantine: Data is invalid; pipeline stops or diverts; not used downstream

2. Function Tokens (Component/Action Type)

2.1 Processing Functions

Token	Color	Hex	Text	Semantic Meaning	Usage
`func.etl`	Purple	`#7b1fa2`	`#fff`	Active data transformation	ETL jobs, processing steps
`func.etl.light`	Light Purple	`#ba68c8`	`#111`	ETL sub-operations	Transform, enrich, aggregate
`func.infra`	Dark Gray	`#424242`	`#fff`	Infrastructure/platform services	CloudWatch, S3, Glue Catalog, Root nodes
`func.infra.light`	Medium Gray	`#616161`	`#fff`	Infrastructure sub-components	Sub-services, configs

2.2 Control Functions

Token	Color	Hex	Text	Semantic Meaning	Usage
`control.decision`	Yellow	`#fbc02d`	`#111`	Conditional logic, validation gates	Decision diamonds, validation checks
`control.testing`	Light Green	`#66bb6a`	`#111`	Quality gates, tests	Unit tests, integration tests, smoke tests
`control.cicd`	Indigo	`#5c6bc0`	`#fff`	CI/CD automation	GitHub Actions, Terraform, deployment

2.3 Flow Functions (Edges/Arrows Only)

Token	Color	Hex	Usage	Semantic Meaning
`flow.input`	Light Blue	`#64b5f6`	Edge/arrow color	Data input, external source
`flow.output`	Teal	`#00897b`	Edge/arrow color	Data output, consumption
`flow.io`	Cyan	`#00acc1`	Edge/arrow color	Read/Write operations
`flow.processing`	Purple	`#7b1fa2`	Edge/arrow color	Active transformation flow

Rule: Flow tokens are for edges/arrows, NOT node fills. Nodes use state/func tokens.

3. Status Tokens (Operational States)

Token	Color	Hex	Text	Semantic Meaning	Contract
`status.success`	Dark Green	`#2e7d32`	`#fff`	Successful completion	Operation completed successfully
`status.warning`	Amber	`#ffa000`	`#111`	Attention needed, pipeline continues	Pipeline continues, emits alert/metric; data usable with caveats
`status.error`	Red	`#d32f2f`	`#fff`	Error, pipeline stops/diverts	Pipeline stops or diverts; data not used downstream (same as quarantine)

Warning vs Quarantine Contract:

Warning (status.warning): Pipeline continues, data is usable but needs attention
Quarantine (state.quarantine): Pipeline stops/diverts, data is invalid and not used downstream

4. Special Concept Tokens

Token	Color	Hex	Text	Semantic Meaning	Visual Indicator
`meta.security`	Deep Purple	`#6a1b9a`	`#fff`	Security boundaries, PII handling	🔒 icon in label + border
`meta.observability`	Teal	`#00897b`	`#fff`	Monitoring, logs, metrics, traces	〰️ icon in label + border
`meta.lineage`	Neutral Gray	`#757575`	`#fff`	Versioning, snapshots, time travel	🕐 icon in label + border
`meta.marker`	Gray	`#757575`	`#fff`	System markers, pointers	`_SUCCESS`, `_LATEST.json`, `current/`
`layout.path`	Light Gray	`#bdbdbd`	`#111`	Organizational hierarchy	Path structure nodes (`mortgages/`, `ingest_date=`, `run_id=`)

5. Accessibility Rules (Deterministic Text Colors)

Rule: Text color is determined by background lightness

Background Type	Background Hex Range	Text Color	Example
Dark	`#000000` - `#808080`	`#ffffff`	Bronze, Silver, Gold, ETL, Infra
Light	`#808080` - `#ffffff`	`#111111`	Light variants, Yellow, Light Green

Implementation: Always explicitly specify text color in Mermaid:

Dark backgrounds: color:#fff
Light backgrounds: color:#111

6. Visual Encoding Strategy

Nodes (Entities)

Fill: State token (Bronze/Silver/Gold/Quarantine) OR Function token (ETL/Infra)
Border: Function token (if fill is state) OR Status token (if applicable)
Icon: Special concept indicator (🔒 for security, 〰️ for observability, 🕐 for lineage) - add to label text

Edges (Actions/Flows)

Color: Flow token (input/output/io/processing) - use stroke property
Style: Solid for normal, dashed for conditional, dotted for metadata

Sub-States

Same hue, different lightness: Use .light variant
Same color + modifier: Use icon in label or border style (dotted, dashed)

7. Mermaid Implementation Examples

Example 1: State + Function Separation

Example 2: With Icons (in label text)

Example 3: Decision Points

Example 4: CI/CD Pipeline

8. Complete Token Reference

Quick Reference Table

Category	Token	Hex	Text	Mermaid Usage
State	`state.bronze`	`#f57c00`	`#fff`	`fill:#f57c00,color:#fff`
State	`state.silver`	`#388e3c`	`#fff`	`fill:#388e3c,color:#fff`
State	`state.gold`	`#1976d2`	`#fff`	`fill:#1976d2,color:#fff`
State	`state.quarantine`	`#d32f2f`	`#fff`	`fill:#d32f2f,color:#fff`
Function	`func.etl`	`#7b1fa2`	`#fff`	`fill:#7b1fa2,color:#fff`
Function	`func.infra`	`#424242`	`#fff`	`fill:#424242,color:#fff`
Control	`control.decision`	`#fbc02d`	`#111`	`fill:#fbc02d,color:#111`
Control	`control.testing`	`#66bb6a`	`#111`	`fill:#66bb6a,color:#111`
Control	`control.cicd`	`#5c6bc0`	`#fff`	`fill:#5c6bc0,color:#fff`
Status	`status.success`	`#2e7d32`	`#fff`	`fill:#2e7d32,color:#fff`
Status	`status.warning`	`#ffa000`	`#111`	`fill:#ffa000,color:#111`
Status	`status.error`	`#d32f2f`	`#fff`	`fill:#d32f2f,color:#fff`
Meta	`meta.security`	`#6a1b9a`	`#fff`	`fill:#6a1b9a,color:#fff` or `stroke:#6a1b9a`
Meta	`meta.observability`	`#00897b`	`#fff`	`fill:#00897b,color:#fff`
Meta	`meta.lineage`	`#757575`	`#fff`	`fill:#757575,color:#fff`
Meta	`meta.marker`	`#757575`	`#fff`	`fill:#757575,color:#fff`
Layout	`layout.path`	`#bdbdbd`	`#111`	`fill:#bdbdbd,color:#111`

9. Key Improvements Summary

✅ State vs Function: Clear separation — states for data quality, functions for component types
✅ Blue collisions reduced: Gold = blue; Infrastructure = dark gray; Input/I/O = edges only
✅ Tints/shades: .light variants for sub-states without new hues
✅ Accessibility: Deterministic text colors based on background lightness
✅ Semantic contracts: Clear Warning vs Quarantine definitions
✅ Missing concepts: Security, Observability, Lineage tokens added
✅ Token-based: Reusable design tokens for implementation

10. Migration Checklist

When updating diagrams:

Use state tokens for data layers (Bronze/Silver/Gold/Quarantine)
Use function tokens for components (ETL, Infrastructure, CI/CD)
Apply state+function separation (fill for state, stroke for function where applicable)
Use flow tokens only for edges/arrows, not node fills
Add icons to labels for special concepts (🔒 security, 〰️ observability, 🕐 lineage)
Specify text color explicitly (color:#fff for dark, color:#111 for light)
Use control tokens for decision points and testing
Use status tokens for operational states (success/warning/error)
Test readability in both light and dark themes

Core Principle: State vs Function Separation​

1. State Tokens (Data Quality/State)​

2. Function Tokens (Component/Action Type)​

2.1 Processing Functions​

2.2 Control Functions​

2.3 Flow Functions (Edges/Arrows Only)​

3. Status Tokens (Operational States)​

4. Special Concept Tokens​

5. Accessibility Rules (Deterministic Text Colors)​

6. Visual Encoding Strategy​

Nodes (Entities)​

Edges (Actions/Flows)​

Sub-States​

7. Mermaid Implementation Examples​

Example 1: State + Function Separation​

Example 2: With Icons (in label text)​

Example 3: Decision Points​

Example 4: CI/CD Pipeline​

8. Complete Token Reference​

Quick Reference Table​

9. Key Improvements Summary​

10. Migration Checklist​