"""Single source of truth for the digital-service Mermaid catalog.
Both the rendered gallery (gallery.html) and the reference catalog
(service-team-diagrams.md) are generated from this list, so the code a
reader copies is byte-for-byte the code that was rendered and approved.
House style (see the skill's icons-and-surfaces.md), verified against Mermaid
11.16.0 in InteractiveMermaid: every diagram is MONOTONE-first, with colour
added only where it teaches (the people/automation boundary, success vs. failure,
the one punchline node). Icons are inline FontAwesome — the FREE set, no emoji —
placed at the start of a label: `Node["fas:fa-user Label"]` (`fab:` for brands).
Inline `fas:`/`fab:` tokens only render in the diagram types whose labels pass
through Mermaid's unified text renderer. Each diagram below carries an `icons`
flag saying whether this type paints inline icons:
icons=True → flowchart, stateDiagram-v2, classDiagram, mindmap (inline form),
block-beta, erDiagram labels. Give every actor/system/outcome an
icons=False → sequence, timeline, gitGraph, C4 (token leaks as literal text);
journey, gantt, sankey, xychart (dropped); quadrant, requirement
(the ':' breaks the parser); architecture-beta (its own built-in
server/database/cloud/disk shape icons). Keep labels PLAIN and
All sixteen types render in InteractiveMermaid (vanilla Mermaid 11). The old
"static only" beta limitation is gone — beautiful-mermaid now powers only the
Icon vocabulary (concept -> inline token), one token per concept everywhere:
fas:fa-user resident/user fas:fa-user-tie caseworker/staff
fas:fa-laptop-code engineer/technologist fas:fa-desktop web app
fas:fa-gear api/service fas:fa-folder-open case system fas:fa-database store/db
fas:fa-cloud cloud fas:fa-inbox queue fas:fa-credit-card payments
fas:fa-envelope notifications fas:fa-magnifying-glass find/review
fas:fa-pen-to-square apply/draft fas:fa-upload submit
fas:fa-arrows-rotate update/reconcile fas:fa-robot AI/automation
fas:fa-circle-check success/granted fas:fa-circle-xmark refused/failure
fas:fa-triangle-exclamation needs attention fas:fa-ticket permit issued
fab:fa-github repo/source (brand)
Fields per diagram: id, group, title, keyword, reader_q, when, avoid, notice,
("understand", "Understand users", "Discovery — see the whole service through the user's eyes and decide what matters."),
("design", "Design the service", "Design — turn research into a flow, the handoffs behind it, and the states a case moves through."),
("connect", "Show how it connects", "Architecture — make the moving parts, their boundaries, and their records legible to anyone."),
("deliver", "Plan and deliver", "Delivery — sequence the work and show how change reaches production."),
("measure", "Run and measure", "Live — watch where users drop out and whether the service is getting better."),
# ── Understand users ──────────────────────────────────────────────────────
"reader_q": "Where does the user feel friction across the whole service?",
"Mapping an end-to-end experience across many steps and channels.",
"You want emotion on the record — the score column shows where it hurts.",
"Sharing research with non-technical stakeholders who need the user's view.",
"You need branching or decisions — a journey is a single straight track (use a flowchart).",
"You need system timing or handoffs (use a sequence diagram).",
"notice": "The low scores cluster around account creation and proof of address — that is where to spend design effort.",
title Apply for a parking permit
Search online: 3: Resident
Check eligibility: 4: Resident
Create an account: 2: Resident
Answer questions: 3: Resident
Upload proof of address: 1: Resident
Get confirmation: 5: Resident
Permit arrives: 5: Resident""",
"title": "Service map (mindmap)",
"reader_q": "What are all the parts of this service we have to design and own?",
"Early discovery, laying out users, channels, systems, and policy at once.",
"Building shared vocabulary before anyone commits to a flow.",
"A living inventory of what a service is made of.",
"You need order or sequence — a mindmap has none (use a flowchart or timeline).",
"You need links between branches — a mindmap is a strict tree, not a graph (use a flowchart).",
"notice": "Four branches, one glance: users, channels, systems, policy. Mindmaps render inline icons, so each branch carries its own. Anything not on a branch is a gap in the plan.",
root((Parking permit service))
fas:fa-mobile-screen Channels
fas:fa-clipboard-list Policy
"id": "prioritisation_quadrant",
"title": "Prioritisation quadrant",
"keyword": "quadrantChart",
"reader_q": "Of everything we could build, what do we do first?",
"Ranking a backlog by two forces at once, usually impact against effort.",
"Making a prioritisation call visible and defensible in a workshop.",
"Any two-axis trade-off — value vs. risk, reach vs. cost.",
"You have one dimension only (use a sorted list or a bar chart).",
"The points need exact values — a quadrant shows position, not precision.",
"notice": "Top-left is the sweet spot: high impact, low effort. Accessibility fixes and online payments land there — do them now.",
title Backlog prioritisation
x-axis Low effort --> High effort
y-axis Low impact --> High impact
quadrant-1 Major projects
Online payments: [0.35, 0.9]
Address lookup: [0.25, 0.6]
Accessibility fixes: [0.4, 0.85]
Legacy migration: [0.8, 0.55]
# ── Design the service ────────────────────────────────────────────────────
"reader_q": "How does a request move from the user to a decision?",
"Showing a process with a real decision or branch in it.",
"The lesson is what the user does versus what the service does — group by that boundary.",
"The default diagram; when unsure, this is usually the right one.",
"There is no branching, just a felt experience (use a user journey).",
"The point is timing between systems (use a sequence diagram).",
"notice": "Colour and shape carry the story: the tinted zones split what people do from automation, the diamond is the one decision, and green versus red is the outcome — each node led by an inline icon.",
subgraph Resident["fas:fa-user What the resident does"]
Start(["fas:fa-pen-to-square Start application"]) --> Answer["fas:fa-pen-to-square Answer questions"] --> Submit["fas:fa-upload Submit"]
subgraph Service["fas:fa-gear What the service does"]
Validate["fas:fa-magnifying-glass Validate details"] --> Check{"Eligible?"}
Check -->|Yes| Grant["fas:fa-ticket Issue permit"]
Check -->|No| Refuse["fas:fa-hand Explain refusal"]
Submit -->|on submit| Validate
style Resident fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
style Service fill:#eff6ff,stroke:#2563eb,color:#172554
style Check fill:#fef9c3,stroke:#ca8a04,color:#422006
style Grant fill:#dcfce7,stroke:#16a34a,color:#14532d
style Refuse fill:#fee2e2,stroke:#dc2626,color:#450a0a""",
"id": "integration_sequence",
"title": "Integration sequence",
"keyword": "sequenceDiagram",
"reader_q": "Which systems talk to each other, and in what order?",
"Designing or documenting an integration across services.",
"Strict time order is the point — message one must precede message two.",
"Debugging a handoff: which call fires when, and what replies.",
"The reader needs the user's emotional arc (use a user journey).",
"You are showing allowed states rather than a single run (use a state diagram).",
"notice": "Read top to bottom as time — the resident only ever touches the web app and the payment step; every other hop is system-to-system. Sequence diagrams can't render inline icons, so the message arrows carry the meaning.",
"code": """sequenceDiagram
actor Resident as Resident
participant Web as Web app
participant Case as Case system
participant Pay as Payments
participant Notify as Notifications
Resident->>Web: Submit application
Pay-->>Resident: Take payment
Pay-->>Case: Payment confirmed
Case->>Notify: Send confirmation
Notify-->>Resident: Email and SMS""",
"title": "Case lifecycle (state)",
"keyword": "stateDiagram-v2",
"reader_q": "What states can a case be in, and how does it move between them?",
"Modelling the lifecycle of an application, case, order, or account.",
"You need to show allowed transitions — and which ones are not allowed.",
"There are loops back: sent for more info, then resubmitted.",
"You are showing one specific run through the system (use a sequence diagram).",
"The states are really process steps with no return paths (use a flowchart).",
"notice": "State diagrams render inline icons too — the check marks the granted exit and the cross marks the refused exit, while the warning-flagged 'more info needed' state is the loop where cases stall: one way out of review, two ways in.",
"code": """stateDiagram-v2
state "fas:fa-pen-to-square Draft" as Draft
state "fas:fa-upload Submitted" as Submitted
state "fas:fa-magnifying-glass Under review" as UnderReview
state "fas:fa-triangle-exclamation More info needed" as MoreInfo
state "fas:fa-circle-check Granted" as Granted
state "fas:fa-circle-xmark Refused" as Refused
Draft --> Submitted : resident submits
Submitted --> UnderReview : assigned
UnderReview --> MoreInfo : needs evidence
MoreInfo --> UnderReview : evidence supplied
UnderReview --> Granted : approved
UnderReview --> Refused : rejected
# ── Show how it connects ──────────────────────────────────────────────────
"title": "System context (C4)",
"reader_q": "Who and what does this service touch?",
"Setting the scene: the service as one box among the people and systems around it.",
"Onboarding someone who needs the big picture before any detail.",
"Naming external dependencies and who owns them.",
"You need what is inside the box (use a C4 container diagram or architecture diagram).",
"The audience wants infrastructure, not logical boundaries (use an architecture diagram).",
"notice": "C4 draws the person and the systems as different shapes for free — that shape difference alone separates our permit service from the external payments, notifications, and vehicle-registry systems (C4 renders no inline icons).",
title System context - Parking permit service
Person(resident, "Resident", "Wants a permit")
System(permit, "Permit service", "Apply, pay, receive")
System_Ext(pay, "Payments platform", "Card payments")
System_Ext(notify, "Notifications", "Email and SMS")
System_Ext(dvla, "Vehicle registry", "Vehicle checks")
Rel(resident, permit, "Applies using")
Rel(permit, pay, "Takes payment via")
Rel(permit, notify, "Sends messages via")
Rel(permit, dvla, "Verifies vehicle with")""",
"id": "infra_architecture",
"title": "Infrastructure topology",
"keyword": "architecture-beta",
"reader_q": "How is this deployed, and what connects to what?",
"Showing the runtime shape: services, stores, queues, and the edges between them.",
"The audience is technical and wants the deployment picture.",
"You want grouping by environment or cloud boundary.",
"The audience is non-technical (use a C4 context diagram).",
"You want logical ownership rather than runtime topology (use a C4 context diagram).",
"notice": "This type ships with built-in shape icons — server, database, disk, cloud — so each node's role reads before its label (inline FontAwesome does not apply here). The cloud box shows what is ours to run.",
"code": """architecture-beta
group cloud(cloud)[Cloud]
service web(server)[Web app] in cloud
service api(server)[API] in cloud
service db(database)[Case store] in cloud
service queue(disk)[Message queue] in cloud
"title": "Records model (ER)",
"reader_q": "What records do we hold, and how do they relate?",
"Modelling durable data: the nouns the service stores and their relationships.",
"Agreeing a data model before anyone writes a migration.",
"Showing ownership and cardinality — one application, many documents.",
"You are showing a process or flow (use a flowchart or sequence diagram).",
"The relationships change over time — ER shows structure, not lifecycle.",
"notice": "The crow's feet carry the rule — one resident, many applications; one application, exactly one permit — and ER renders an inline icon on each relationship label, so the verb reads before you trace the line.",
RESIDENT ||--o{ APPLICATION : "fas:fa-paper-plane submits"
APPLICATION ||--|| PERMIT : "fas:fa-ticket results in"
APPLICATION ||--o{ DOCUMENT : "fas:fa-paperclip includes"
CASEWORKER ||--o{ APPLICATION : "fas:fa-magnifying-glass reviews\"""",
"title": "Roles and capabilities (class)",
"keyword": "classDiagram",
"reader_q": "What are the roles, and what can each one do?",
"Modelling responsibilities: what each actor or object is allowed to do.",
"Showing a domain model with methods, not just data.",
"Documenting an API or object model for engineers.",
"The audience is non-technical (use a flowchart or journey).",
"You only have data, no behaviour (use an ER diagram).",
"notice": "Class diagrams render inline icons too — the verbs are the point: the caseworker can decide, while the application can only be submitted or withdrawn.",
class Application["fas:fa-pen-to-square Application"] {
class Caseworker["fas:fa-user-tie Caseworker"] {
Caseworker --> Application : processes""",
# ── Plan and deliver ──────────────────────────────────────────────────────
"id": "delivery_roadmap",
"title": "Delivery roadmap (Gantt)",
"reader_q": "What is the plan, and in what order?",
"Sequencing phases and tasks against real dates.",
"Showing dependencies — this task starts after that one.",
"A delivery plan a sponsor can read at a glance.",
"Dates are unknown or irrelevant (use a timeline).",
"The plan has branches or decisions, not a fixed schedule (use a flowchart).",
"notice": "The critical line runs straight down the 'after' chain — every task starts after the last, so every slip in discovery pushes beta to the right.",
User research :a1, 2026-01-06, 20d
Service map :a2, after a1, 10d
Prototype :b1, after a2, 25d
Usability testing :b2, after b1, 15d
Build MVP :c1, after b2, 40d
Private beta :c2, after c1, 20d""",
"id": "service_timeline",
"title": "Service phases (timeline)",
"reader_q": "How has the service evolved, and what comes next?",
"Showing phases or milestones without needing exact dates.",
"Telling the story of a service across discovery, alpha, beta, live.",
"A lightweight roadmap for a non-technical audience.",
"You need task dependencies or durations (use a Gantt chart).",
"You need exact dates on each item (use a Gantt chart).",
"notice": "Each phase names its own purpose, not just its point in time — so the reader sees not just when but why the service changed shape.",
Discovery : Understand users : Map the service
Alpha : Prototype : Test the riskiest assumptions
Beta : Build the MVP : Private then public beta
Live : Continuous improvement : Meet the service standard""",
"title": "Release flow (git graph)",
"reader_q": "How does a change reach production?",
"Explaining a branching and release strategy to a team.",
"Showing where a change is cut, reviewed, merged, and tagged.",
"Onboarding engineers to how the repo is run.",
"The audience does not use git (use a flowchart).",
"You are explaining a process, not branch topology (use a flowchart).",
"notice": "Work happens on a branch and lands on main in one merge — the version tag marks what actually shipped.",
commit id: "add validation"
commit id: "release" tag: "v1.1\"""",
# ── Run and measure ───────────────────────────────────────────────────────
"title": "Drop-out funnel (Sankey)",
"keyword": "sankey-beta",
"reader_q": "Where do users fall out of the service?",
"Showing volume flowing through a funnel, with the leaks called out.",
"Turning analytics into a picture: how many started, finished, abandoned.",
"Making a conversion problem impossible to ignore.",
"You need a trend over time (use an XY chart).",
"The categories are not a flow — you are comparing independent amounts (use a bar chart).",
"notice": "Sankey needs no icons — band width does the encoding. The fat Abandoned band after Started is the whole story: nearly two in five who start never finish.",
Visited,Started application,1000
Started application,Completed application,620
Started application,Abandoned,380
Completed application,Paid,540
Completed application,Payment failed,80
Paid,Permit issued,540""",
"title": "KPI trend (XY chart)",
"keyword": "xychart-beta",
"reader_q": "Is the service getting better?",
"Tracking a metric over ordered buckets — months, weeks, sprints.",
"Showing a trend a sponsor can read in two seconds.",
"Comparing a count and a rate on the same axis.",
"The buckets are not ordered (use a bar comparison or table).",
"You are showing where volume goes, not how it trends (use a Sankey).",
"notice": "The line only goes up and to the right — completion has climbed every month since launch.",
title "Completion rate by month"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Percent completed" 0 --> 100
bar [58, 61, 66, 70, 74, 79]
line [58, 61, 66, 70, 74, 79]""",
"id": "assurance_requirements",
"title": "Assurance traceability (requirement)",
"keyword": "requirementDiagram",
"reader_q": "Which requirements does this service satisfy, and how do we know?",
"Tracing requirements to the components that satisfy them.",
"Assurance, audit, or accreditation work — showing coverage and risk.",
"Making a verification method explicit for each requirement.",
"You just need a checklist with no traceability (use a table).",
"You are showing a process or flow (use a flowchart).",
"notice": "Every requirement carries its own risk and how it will be verified — the arrow is the evidence trail.",
"code": """requirementDiagram
requirement accessibility {
permit_form - satisfies -> accessibility""",