Skip to content

nWave-ai/nWave / nWave/skills/nw-diagram

nw-diagram

Verified

Generates accessible, legible C4 architecture diagrams (context, container, component) in Mermaid or PlantUML under 12 checkable rules. Use when creating, updating or reviewing architecture diagrams, or when documents.readable_brief is enabled.

NW-DIAGRAM: Accessible Architecture Diagrams

Wave: CROSS_WAVE | Agent: Morgan (nw-solution-architect), semantic content only | Command: /nw-diagram

Overview

Generate architecture diagrams from the existing design context, as C4 levels (context|container|component) in Mermaid|PlantUML|C4. A correct diagram that a person cannot read has failed. Every rule below is checkable from the source text, without rendering. This standalone visualization does not author or replace architecture authority. Reviewers (documentarist) apply the same rules.

Context Files Required

  • docs/product/architecture/brief.md (SSOT — component boundaries, technology stack, design decisions)

Legibility and accessibility rules

Colour, contrast, text alternative and screen-reader duties come from the accessibility section of nw-usability-engineering ("Accessibility as Design Constraint"). The rules apply them to diagram source.

#RuleCheck in the source
R1Title inside the blockC4: a title line. Other types: front matter title: as first lines. accTitle/accDescr where the type supports them (flowchart, sequence)
R2Prose description directly above the block1-3 sentences starting This diagram shows: immediately before the fence. HTML shows it above the diagram
R3At most 25 nodes per block (provisional limit)Count node ids. Above 25, split by subsystem or wave and link the blocks in prose
R4Node label at most 40 characters and 2 line breaksCount characters per label. Detail goes to the description or a table
R5Reading direction stated and standardTD for phased flows, LR for pipelines. BT only for Mikado trees, with a sentence saying goals sit on top
R6Colour never the only signalEach class also differs by shape, dash style or label prefix
R7Contrast declared and sufficientEach classDef sets fill, stroke and color. Fill vs stroke at least 3:1, fill vs text at least 4.5:1, recalculated from the hex codes
R8Legend when styles existA classDef or style means a LEGEND subgraph with one node per class
R9Human names for groups above 8 nodesEach subgraph title is a subsystem name, not a code
R10Short edge labels, not repeatedAt most 4 words. The same label at most 4 times. Otherwise group the edges or drop the label
R11Acronyms and ids expanded onceEvery acronym or id (E1, SYS-4) appears expanded in the title, legend or description
R12One C4 level per blockNo context, container and component elements in one block. The title names the level (L1, L2, L3)

Old diagrams under docs/archive stay as they are. The rules bind new and regenerated diagrams.

Workflow

  1. Read Context — Load docs/product/architecture/brief.md. Extract component boundaries, technology stack, and design decisions.
  2. Resolve Configuration — Determine diagram_type (component|deployment|sequence|data|context), format (mermaid|plantuml|c4), level (context|container|component), and, if files are requested, output_directory.
  3. Invoke Agent — Ask @nw-solution-architect for the semantic diagram content in the selected format for {architecture-component}, using the brief as context and R1-R12. Do not ask the architect to write diagram files or architecture-document bytes.
  4. Check and Render — The caller checks R1-R12 on the returned source and returns each failed rule to the architect with its rule id. Then it checks the content with the selected renderer. If files were requested, the caller writes the validated source to output_directory and checks that the files exist; never delegate those writes to the architect.
  5. Handoff — Return the diagram content or caller-written artifacts to the invoking workflow.

Success Criteria

  • Diagrams accurately represent current architecture
  • Audience-appropriate detail level applied
  • R1-R12 hold for every block, or the exception is named in the description
  • Diagrams render without syntax errors
  • Requested output files, if any, created by the caller in the configured directory

Next Wave

Handoff To: {invoking-agent-returns-to-workflow} Deliverables: Diagram content in the configured format, and caller-written files if requested

Examples

Example 1: Generate a C4 container diagram

/nw-diagram payment-service --diagram_type=component --format=mermaid --level=container

Morgan returns Mermaid container content with a title line naming L2, at most 25 nodes, short labels and a description sentence. The caller checks R1-R12, renders it and writes a file if requested.

Example 2: A phase map with 71 nodes (fails R3, R4, R8)

Split it into one block per wave. Shorten each label to 40 characters and move the detail into the description. Add a LEGEND subgraph for the four classDef classes and give each class its own shape.

Example File Output (when requested)

docs/product/architecture/
  payment-service-container.mmd
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall