Override default Mermaid/diagram aesthetics. Replaces grey nodes, single-colour diagrams, and cramped layouts with spectral node colouring, OLED-optimised backgrounds, and semantic visual hierarchy. Triggers on diagram creation, flowcharts, architecture diagrams, sequence diagrams, and ER diagrams.
context
fork
Diagram uplift
LLMs produce Mermaid diagrams with predictable failure modes: the default grey theme with black text, monochromatic node colouring that conveys no semantic meaning, top-down direction regardless of data flow, and zero subgraph grouping for bounded contexts. This skill replaces those defaults with spectral node colouring mapped to semantic purpose, OLED-optimised backgrounds, and layout direction that matches the diagram's conceptual flow.
The skill is rigid. Every diagram produced under its governance must pass the eval criteria at the end of this file. There are no soft recommendations here — each rule exists because its violation is detectable and its correction is measurable.
When to apply
Positive triggers
Activate this skill when the task involves producing or revising diagrams:
All nodes appear equally important; the reader cannot distinguish data stores from decision points from external services
Minimum three colours per diagram, each mapped to a semantic category
4
TD (top-down) direction for everything
Sequential processes and data pipelines flow naturally left-to-right; forcing TD creates unnecessarily tall, narrow diagrams
LR for sequential flows and pipelines; TD for hierarchical relationships and org charts
5
No subgraph grouping
Flat diagrams with 10+ nodes become unreadable; bounded contexts are invisible
Subgraph boundaries for every logical grouping (frontend/backend, service boundaries, phases)
6
Default arrow styles (thin, no labels)
Relationships between nodes carry no meaning beyond "connected to"
Labelled arrows with semantic thickness; dotted for async, solid for sync, thick for critical path
7
LR (left-to-right) for hierarchical processes
Tree structures and dependency graphs read naturally top-down; forcing LR creates wide, shallow diagrams that scroll horizontally
TD for hierarchies, dependency trees, and inheritance diagrams
8
Text-heavy nodes (more than 4 words)
Long labels create oversized nodes that distort the layout and compete with the diagram's structural information
Maximum 4 words per node label; move detail to annotations or a legend
Reference: See references/anti-patterns.md for full before/after examples of each pattern.
Replacement standards
These rules govern all diagram output when this skill is active.
Spectral node colouring
Every node in a diagram must be coloured according to its semantic role. The colour mapping is not decorative — it encodes information. A reader should be able to glance at a diagram and immediately distinguish data stores from decision points from external services, without reading any labels.
The Scientific Luxury spectral palette provides five semantic categories that cover the vast majority of system diagram node types. When a node does not fit cleanly into one category, choose the closest match. Never leave a node in the default grey.
Layout direction
Choose the direction that matches the diagram's conceptual flow. Sequential processes — authentication flows, data pipelines, request lifecycles — flow left-to-right because the reader's eye naturally follows this direction for temporal sequences. Hierarchical structures — component trees, dependency graphs, organisational charts — flow top-down because parent-child relationships read naturally as vertical.
When a diagram contains both sequential and hierarchical elements, prefer LR for the primary flow and use subgraphs with internal TD direction for hierarchical subsections.
Subgraph boundaries
Every diagram with more than six nodes must use subgraph grouping. Subgraphs map to bounded contexts: frontend vs backend, service boundaries, processing phases, or deployment zones. The subgraph title should name the boundary (e.g., "Frontend", "Auth Service", "Phase 1: Validation") rather than describe its contents.
Subgraph backgrounds use #0a0a0a — one shade lighter than the OLED base — to create subtle containment without harsh borders.
Arrow semantics
Arrows carry meaning beyond simple connection. Synchronous calls use solid lines. Asynchronous messages use dotted lines. Critical path flows use thick lines. Data flow labels describe what is transmitted, not the mechanism: "JWT token" rather than "HTTP response", "user credentials" rather than "POST request".
Styling references
For Scientific Luxury projects, apply references/standards.md — the full spectral theme configuration, node colour mapping table, and Mermaid init block.
For all other projects, apply references/standards-generic.md — a professional dark-mode palette with clean node styling that works in any Markdown renderer.
Node colour mapping
Node types mapped to spectral colours. This table is the authoritative reference for which colour to apply to which node.
Node type
Colour
Hex
Usage
Data / storage
Cyan
#00F5FF
Databases, caches, file stores, message queues, state stores
When a node serves multiple purposes, colour it by its primary role in the diagram's narrative. A database that stores error logs is still a data node (Cyan), not an error node (Red), because its architectural role is storage.
Mermaid theme init block
Every Mermaid diagram produced under this skill must begin with this init block. Paste it verbatim before the diagram direction declaration.
This configuration sets the OLED black background, spectral primary/secondary/tertiary colours, semi-transparent borders that avoid harsh edges, and JetBrains Mono for precise label alignment.
For node-specific colouring beyond the three theme slots, use inline style directives after the node declaration:
All diagram labels, annotations, and surrounding prose must use Australian English spelling and conventions.
Spelling: colour, behaviour, optimisation, organised, licence (noun), analyse, centre, defence, honour, programme (but "program" for software).
Dates use DD/MM/YYYY format. Currency uses AUD ($). Times reference AEST or AEDT. Node labels use sentence case — "User authentication" not "User Authentication".
Eval criteria
Every diagram produced under this skill must pass all eight checks. A single failure means the diagram requires revision.
#
Criterion
PASS condition
1
Theme init block
Diagram begins with the %%{init}%% block (or generic equivalent). No default Mermaid theme.
2
Spectral colouring
Every node is coloured according to the node colour mapping table. No grey or default-coloured nodes.
3
Minimum three colours
At least three distinct spectral colours appear in the diagram. Single-colour diagrams are rejected.
4
Correct direction
LR for sequential flows, TD for hierarchies. Direction matches the conceptual flow of the content.
5
Subgraph grouping
Diagrams with more than six nodes use subgraph boundaries for bounded contexts.
6
Node label brevity
No node label exceeds 4 words. Detail is in annotations or a legend, not crammed into node text.
7
Arrow semantics
Arrows use labels, and line style distinguishes sync from async where both exist in the same diagram.
8
en-AU compliance
Australian spelling in all labels and annotations. Sentence case for node labels. DD/MM/YYYY for any dates.
Run this checklist mentally before declaring any diagram task complete. If any criterion fails, fix it before delivering.
