Cursor Skill

architecture-diagrams

Author and visually review evidence-based software architecture diagrams as D2 v0.7.1 source rendered with ELK to canonical SVG.

LLM Mart · 0 points · 5 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download unoplat-unoplat-code-confluence-unoplat-code-confluence-query-engine_src_unoplat_code_confluence_query_engine_skills_architecture-diagrams-c66c489.zip · 10 KB

unoplat/unoplat-code-confluence 94 7 forks Updated 22d ago

Part of unoplat/unoplat-code-confluence — 3 skills

Install

skills CLI

npx skills add https://github.com/unoplat/unoplat-code-confluence/tree/dev/unoplat-code-confluence-query-engine/src/unoplat_code_confluence_query_engine/skills/architecture-diagrams

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install unoplat-unoplat-code-confluence@llmmart

Git git clone https://github.com/unoplat/unoplat-code-confluence.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole unoplat/unoplat-code-confluence collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

D2 Architecture Diagrams

Use this guide to create or review the repository architecture from current, explicit evidence. The diagram must answer one architectural question clearly; it is not an exhaustive code inventory.

This skill contains authoring guidance and URL-only icon catalogs. It has no executable skill scripts. Runtime artifact ownership, console tools, and the validate_architecture finish rule are defined by the agent instructions—follow those for what you may write and which tools to call. This skill defines how to author and visually approve architecture.d2.

Source format and render expectations

Author unfenced D2 only in architecture.d2. Do not wrap the source in a Markdown document or code fence.
Target D2 v0.7.1 with ELK. The validator owns syntax checks, version enforcement, rendering, atomic architecture.svg replacement, and digests.
The only persisted render is SVG. The validator may attach a temporary visual preview of the exact generated SVG for review; that preview is not a repository artifact and must not be written into the repo.
Do not judge final layout from D2 source alone. Inspect the validator preview against the checklists in this skill. Any source edit after a successful validation requires another validate + visual review (see agent finish rule and §8 below).

1. Build an evidence inventory first

Read every explicitly listed, fresh app_interfaces.md artifact. Consult only the minimal source, configuration, deployment, or infrastructure evidence needed to confirm a claim. Do not use stale or unlisted interface artifacts and do not invent components, protocols, dependencies, ownership, or deployment boundaries.

Before writing D2, record a concise inventory:

Nodes: actors, entry points, deployable applications and services, data stores, queues, and external systems.
Boundaries: supported ownership, deployment, trust, network, or subsystem boundaries.
Relationships: source, target, semantic direction, action label, and interaction type.
Scope: the primary question, abstraction level, and deliberate omissions.
Visual vocabulary: the meaning of shapes, colors, line patterns, and icons.

Treat the relationship inventory as a non-regression checklist. Layout or style changes must never silently remove, merge, reverse, or mislabel an interaction. Co-location in a deployment file proves membership, not communication.

Model independently meaningful runtime nodes. Omit package directories, shared source modules, and library-only codebases unless the chosen architectural question specifically concerns components inside one runtime.

2. Keep one abstraction level

Choose one primary level and architectural question:

Context: people and external systems around the system.
Container: independently deployable applications, services, and stores.
Component: important modules inside one application or service.
Deployment: runtime nodes, environments, networks, and infrastructure.
Data flow: production, transformation, persistence, and consumption.

Do not combine all levels in one image. Prefer a focused system-level diagram; if multiple views are truly required, use D2 boards or composition rather than crowding unrelated detail together.

Responsibility-oriented container groupings often include consumers and entry points, repository-owned backend services, platform/infrastructure, and external services. Create only evidence-backed, non-empty groups. These roles are useful organization aids, not mandatory decorative boxes.

3. Use stable keys and meaningful containers

Separate machine-friendly keys from reader-facing labels. Relationships must reference keys, including qualified keys across containers:

client_tier: Client tier {
  web_app: Web application
}

service_tier: Service tier {
  order_api: Order API
}

client_tier.web_app -> service_tier.order_api: submit order

Use lower-case stable keys that survive label changes. Keep labels concise and specific. Use containers only when they communicate ownership, deployment, trust, runtime, network, or internal/external responsibility. Keep nesting shallow unless another level adds architectural meaning.

4. Establish topology before styling

Add nodes, boundaries, and evidence-backed relationships before colors, icons, or spacing controls. Select one global direction from the dominant reading order:

direction: right

users -> web_app: send requests
web_app -> api: call API
api -> worker: enqueue job
worker -> database: persist result

Use right when the dominant flow is users → application → dependencies. Use down when it is entry points → processing → persistence. ELK is hierarchical: nested containers do not have independent flow directions. Render promising global directions rather than judging layout from source alone.

Declare the dominant semantic flow in the chosen reading direction when possible. Keep edge labels short, action-oriented, and evidence-backed, such as send request, publish event, read profile, or persist result. Avoid endpoint-name repetition and prose paragraphs on edges.

Preserve the true semantic arrow direction. If available evidence establishes a relationship but not direction, do not invent one.

Reverse and feedback flows

First render the semantically direct edge:

notification_service -> web_app: send live update

A literal reverse edge can create a large loop in a layered layout. Only when it materially damages readability may you declare the edge in the layout direction and place the visible arrowhead at its source:

# Ranked forward for ELK; the visible arrow still points to web_app.
web_app -> notification_service: send live update {
  source-arrowhead: {
    shape: triangle
  }
  target-arrowhead: {
    shape: none
  }
}

Use this workaround sparingly. Add an explanatory source comment, inspect the rendered arrowhead, confirm the visible direction is semantically correct, and prefer the direct edge whenever its layout is acceptable.

5. Define a small semantic visual language

Use a few reusable classes rather than duplicating attributes. Useful edge semantics are synchronous request, asynchronous event/work, data access or replication, and external integration:

classes: {
  service: {
    style: {
      border-radius: 8
      shadow: true
    }
  }
  request: {
    style: {
      stroke: "#2563EB"
      stroke-width: 2
    }
  }
  event: {
    style: {
      stroke: "#7C3AED"
      stroke-width: 2
      stroke-dash: 4
    }
  }
  data: {
    style: {
      stroke: "#B45309"
      stroke-width: 2
    }
  }
  external: {
    style: {
      stroke: "#047857"
      stroke-width: 2
    }
  }
}

api: API {class: service}
worker: Worker {class: service}
api -> worker: publish task {class: event}

These colors are examples, not required choices. Meaning must never depend on color alone: combine color with an action label, dash pattern, arrow style, or shape. Use object-level overrides only for intentional exceptions.

Keep styling restrained: light container fills, clear borders, consistent leaf styles, modest rounding or shadows, and hierarchy-appropriate font sizes. Avoid a unique color or shape for every node. Maintain sufficient contrast and text size at the expected documentation scale.

6. Use only exact catalog icon URLs

Icons are optional recognition aids, not a type system or a substitute for text. Use them mainly on recognizable leaf nodes such as a database, language, cloud service, or external product. Prefer a labeled node with an icon; use shape: image only when an icon-only element is genuinely appropriate.

Before adding an icon, call read_skill_resource with skill name architecture-diagrams and one of these exact resource names:

icons/development/catalog.json for hosted dev/ icons
icons/technology/catalog.json for hosted tech/ icons
icons/infrastructure/catalog.json for hosted infra/ icons
icons/README.md for storage, runtime, licensing, and refresh policy

Use only an exact HTTPS url from a packaged catalog. Never guess a filename, use an arbitrary host, use a local icon path, or copy and redistribute hosted SVG bytes. Keep labels beside icons, avoid product logos on broad subsystem containers, and use a coherent family where practical.

database: Application database {
  icon: https://icons.d2lang.com/dev/postgresql.svg
}

Hosted icons require outbound access to https://icons.d2lang.com during the complete D2 render. Validation alone does not prove reachability. D2 embeds the fetched icon in the final SVG, so that rendered artifact is self-contained. If the renderer has no internet access, omit the icon or use a built-in D2 shape instead of creating a broken reference. Re-render after adding icons because they change node dimensions and routing.

The catalogs are URL metadata, not a blanket license or trademark grant. Use third-party marks only for accurate identification, do not imply endorsement, and follow applicable brand and usage policies.

7. Tune spacing last

Wait until nodes, boundaries, relationships, direction, classes, and icons are stable. Then adjust one concern at a time:

Increase layer spacing when edge labels are cramped.
Increase edge-to-node spacing when routes pass too close to nodes.
Increase container padding when children crowd borders or titles.
Reduce spacing carefully when the composition is unnecessarily large.

Do not copy unknown ELK flags from another D2 release. The validator controls the canonical v0.7.1 render. Prefer simple source-level topology and direction changes; request validator changes separately if a canonical ELK option is truly required.

8. Validate, inspect, and revise

Use this sequence:

Build and check the node, boundary, relationship, scope, and vocabulary inventory.
Choose one abstraction level and one global reading direction.
Author the unstyled topology in architecture.d2.
Correct hierarchy and feedback-flow problems without changing semantics.
Add small semantic classes and restrained styling.
Load exact icon catalogs and add only useful icons.
Tune spacing one concern at a time.
Re-read the complete D2 source and compare it with the evidence inventory.
Call validate_architecture with no arguments.
Inspect the attached temporary preview of the exact canonical SVG at full resolution and expected embedded size.
Repair every structural or visual issue, then re-read, revalidate, and inspect again.
Load this skill again for final review. Finish only when the latest source and render digests correspond to the visually approved artifacts.

Compilation is necessary but not visual approval. Reject a render with unnecessary crossings, overlapping edges, routes through nodes or labels, ambiguous label association, excessive bends, dominant reverse-flow loops, cluttered boundaries, or unreadable text. Never remove or reverse an architecture fact merely to improve layout.

Correctness and non-regression

Every in-scope node and meaningful boundary is present.
Every required relationship remains present and correctly labeled.
Visible arrowheads point in the true semantic direction.
Containers represent real boundaries rather than decoration.
The final topology still matches the evidence inventory.
No unsupported component, protocol, dependency, or ownership claim was introduced.

Readability

The primary reading order is immediately apparent.
Edge labels associate clearly with their relationships.
Crossings, bends, and feedback loops are limited.
Text remains readable at documentation size.
Classes have consistent meanings.
Icons improve recognition without replacing labels.

Accessibility

Meaning does not depend only on color.
Container fills, borders, labels, and edges have sufficient contrast.
Fonts are legible at the intended size.
Unfamiliar icons have accompanying text.

Official references

Files (unoplat-code-confluence)

icons

development

catalog.json 19.4 KB

{
  "schema_version": 1,
  "source": "https://icons.d2lang.com/",
  "storage_policy": "hosted-url-references-only",
  "requires_internet_to_render": true,
  "category": "development",
  "hosted_prefix": "dev",
  "icon_count": 123,
  "icons": [
    {
      "name": "amazonwebservices",
      "label": "Amazonwebservices",
      "hosted_path": "dev/amazonwebservices.svg",
      "url": "https://icons.d2lang.com/dev/amazonwebservices.svg"
    },
    {
      "name": "android",
      "label": "Android",
      "hosted_path": "dev/android.svg",
      "url": "https://icons.d2lang.com/dev/android.svg"
    },
    {
      "name": "angularjs",
      "label": "Angularjs",
      "hosted_path": "dev/angularjs.svg",
      "url": "https://icons.d2lang.com/dev/angularjs.svg"
    },
    {
      "name": "apache",
      "label": "Apache",
      "hosted_path": "dev/apache.svg",
      "url": "https://icons.d2lang.com/dev/apache.svg"
    },
    {
      "name": "appcelerator",
      "label": "Appcelerator",
      "hosted_path": "dev/appcelerator.svg",
      "url": "https://icons.d2lang.com/dev/appcelerator.svg"
    },
    {
      "name": "apple",
      "label": "Apple",
      "hosted_path": "dev/apple.svg",
      "url": "https://icons.d2lang.com/dev/apple.svg"
    },
    {
      "name": "atom",
      "label": "Atom",
      "hosted_path": "dev/atom.svg",
      "url": "https://icons.d2lang.com/dev/atom.svg"
    },
    {
      "name": "babel",
      "label": "Babel",
      "hosted_path": "dev/babel.svg",
      "url": "https://icons.d2lang.com/dev/babel.svg"
    },
    {
      "name": "backbonejs",
      "label": "Backbonejs",
      "hosted_path": "dev/backbonejs.svg",
      "url": "https://icons.d2lang.com/dev/backbonejs.svg"
    },
    {
      "name": "bitbucket",
      "label": "Bitbucket",
      "hosted_path": "dev/bitbucket.svg",
      "url": "https://icons.d2lang.com/dev/bitbucket.svg"
    },
    {
      "name": "bootstrap",
      "label": "Bootstrap",
      "hosted_path": "dev/bootstrap.svg",
      "url": "https://icons.d2lang.com/dev/bootstrap.svg"
    },
    {
      "name": "bower",
      "label": "Bower",
      "hosted_path": "dev/bower.svg",
      "url": "https://icons.d2lang.com/dev/bower.svg"
    },
    {
      "name": "c",
      "label": "C",
      "hosted_path": "dev/c.svg",
      "url": "https://icons.d2lang.com/dev/c.svg"
    },
    {
      "name": "cakephp-plain-wordmark",
      "label": "Cakephp Plain Wordmark",
      "hosted_path": "dev/cakephp-plain-wordmark.svg",
      "url": "https://icons.d2lang.com/dev/cakephp-plain-wordmark.svg"
    },
    {
      "name": "ceylon",
      "label": "Ceylon",
      "hosted_path": "dev/ceylon.svg",
      "url": "https://icons.d2lang.com/dev/ceylon.svg"
    },
    {
      "name": "chrome",
      "label": "Chrome",
      "hosted_path": "dev/chrome.svg",
      "url": "https://icons.d2lang.com/dev/chrome.svg"
    },
    {
      "name": "clojure",
      "label": "Clojure",
      "hosted_path": "dev/clojure.svg",
      "url": "https://icons.d2lang.com/dev/clojure.svg"
    },
    {
      "name": "clojurescript",
      "label": "Clojurescript",
      "hosted_path": "dev/clojurescript.svg",
      "url": "https://icons.d2lang.com/dev/clojurescript.svg"
    },
    {
      "name": "codeigniter",
      "label": "Codeigniter",
      "hosted_path": "dev/codeigniter.svg",
      "url": "https://icons.d2lang.com/dev/codeigniter.svg"
    },
    {
      "name": "codepen",
      "label": "Codepen",
      "hosted_path": "dev/codepen.svg",
      "url": "https://icons.d2lang.com/dev/codepen.svg"
    },
    {
      "name": "confluence",
      "label": "Confluence",
      "hosted_path": "dev/confluence.svg",
      "url": "https://icons.d2lang.com/dev/confluence.svg"
    },
    {
      "name": "couchdb",
      "label": "Couchdb",
      "hosted_path": "dev/couchdb.svg",
      "url": "https://icons.d2lang.com/dev/couchdb.svg"
    },
    {
      "name": "cplusplus",
      "label": "Cplusplus",
      "hosted_path": "dev/cplusplus.svg",
      "url": "https://icons.d2lang.com/dev/cplusplus.svg"
    },
    {
      "name": "csharp",
      "label": "Csharp",
      "hosted_path": "dev/csharp.svg",
      "url": "https://icons.d2lang.com/dev/csharp.svg"
    },
    {
      "name": "css3",
      "label": "Css",
      "hosted_path": "dev/css3.svg",
      "url": "https://icons.d2lang.com/dev/css3.svg"
    },
    {
      "name": "cucumber",
      "label": "Cucumber",
      "hosted_path": "dev/cucumber.svg",
      "url": "https://icons.d2lang.com/dev/cucumber.svg"
    },
    {
      "name": "d3js",
      "label": "D3js",
      "hosted_path": "dev/d3js.svg",
      "url": "https://icons.d2lang.com/dev/d3js.svg"
    },
    {
      "name": "debian",
      "label": "Debian",
      "hosted_path": "dev/debian.svg",
      "url": "https://icons.d2lang.com/dev/debian.svg"
    },
    {
      "name": "devicon",
      "label": "Devicon",
      "hosted_path": "dev/devicon.svg",
      "url": "https://icons.d2lang.com/dev/devicon.svg"
    },
    {
      "name": "django",
      "label": "Django",
      "hosted_path": "dev/django.svg",
      "url": "https://icons.d2lang.com/dev/django.svg"
    },
    {
      "name": "docker",
      "label": "Docker",
      "hosted_path": "dev/docker.svg",
      "url": "https://icons.d2lang.com/dev/docker.svg"
    },
    {
      "name": "doctrine",
      "label": "Doctrine",
      "hosted_path": "dev/doctrine.svg",
      "url": "https://icons.d2lang.com/dev/doctrine.svg"
    },
    {
      "name": "dotnet",
      "label": "Dotnet",
      "hosted_path": "dev/dotnet.svg",
      "url": "https://icons.d2lang.com/dev/dotnet.svg"
    },
    {
      "name": "drupal",
      "label": "Drupal",
      "hosted_path": "dev/drupal.svg",
      "url": "https://icons.d2lang.com/dev/drupal.svg"
    },
    {
      "name": "electron",
      "label": "Electron",
      "hosted_path": "dev/electron.svg",
      "url": "https://icons.d2lang.com/dev/electron.svg"
    },
    {
      "name": "elm",
      "label": "Elm",
      "hosted_path": "dev/elm.svg",
      "url": "https://icons.d2lang.com/dev/elm.svg"
    },
    {
      "name": "ember",
      "label": "Ember",
      "hosted_path": "dev/ember.svg",
      "url": "https://icons.d2lang.com/dev/ember.svg"
    },
    {
      "name": "erlang",
      "label": "Erlang",
      "hosted_path": "dev/erlang.svg",
      "url": "https://icons.d2lang.com/dev/erlang.svg"
    },
    {
      "name": "firefox",
      "label": "Firefox",
      "hosted_path": "dev/firefox.svg",
      "url": "https://icons.d2lang.com/dev/firefox.svg"
    },
    {
      "name": "foundation",
      "label": "Foundation",
      "hosted_path": "dev/foundation.svg",
      "url": "https://icons.d2lang.com/dev/foundation.svg"
    },
    {
      "name": "gatling",
      "label": "Gatling",
      "hosted_path": "dev/gatling.svg",
      "url": "https://icons.d2lang.com/dev/gatling.svg"
    },
    {
      "name": "gimp",
      "label": "Gimp",
      "hosted_path": "dev/gimp.svg",
      "url": "https://icons.d2lang.com/dev/gimp.svg"
    },
    {
      "name": "git",
      "label": "Git",
      "hosted_path": "dev/git.svg",
      "url": "https://icons.d2lang.com/dev/git.svg"
    },
    {
      "name": "github",
      "label": "Github",
      "hosted_path": "dev/github.svg",
      "url": "https://icons.d2lang.com/dev/github.svg"
    },
    {
      "name": "gitlab",
      "label": "Gitlab",
      "hosted_path": "dev/gitlab.svg",
      "url": "https://icons.d2lang.com/dev/gitlab.svg"
    },
    {
      "name": "go",
      "label": "Go",
      "hosted_path": "dev/go.svg",
      "url": "https://icons.d2lang.com/dev/go.svg"
    },
    {
      "name": "gradle",
      "label": "Gradle",
      "hosted_path": "dev/gradle.svg",
      "url": "https://icons.d2lang.com/dev/gradle.svg"
    },
    {
      "name": "grails",
      "label": "Grails",
      "hosted_path": "dev/grails.svg",
      "url": "https://icons.d2lang.com/dev/grails.svg"
    },
    {
      "name": "groovy",
      "label": "Groovy",
      "hosted_path": "dev/groovy.svg",
      "url": "https://icons.d2lang.com/dev/groovy.svg"
    },
    {
      "name": "grunt",
      "label": "Grunt",
      "hosted_path": "dev/grunt.svg",
      "url": "https://icons.d2lang.com/dev/grunt.svg"
    },
    {
      "name": "gulp",
      "label": "Gulp",
      "hosted_path": "dev/gulp.svg",
      "url": "https://icons.d2lang.com/dev/gulp.svg"
    },
    {
      "name": "handlebars",
      "label": "Handlebars",
      "hosted_path": "dev/handlebars.svg",
      "url": "https://icons.d2lang.com/dev/handlebars.svg"
    },
    {
      "name": "haskell",
      "label": "Haskell",
      "hosted_path": "dev/haskell.svg",
      "url": "https://icons.d2lang.com/dev/haskell.svg"
    },
    {
      "name": "heroku",
      "label": "Heroku",
      "hosted_path": "dev/heroku.svg",
      "url": "https://icons.d2lang.com/dev/heroku.svg"
    },
    {
      "name": "html5",
      "label": "Html",
      "hosted_path": "dev/html5.svg",
      "url": "https://icons.d2lang.com/dev/html5.svg"
    },
    {
      "name": "ie",
      "label": "Ie",
      "hosted_path": "dev/ie.svg",
      "url": "https://icons.d2lang.com/dev/ie.svg"
    },
    {
      "name": "illustrator",
      "label": "Illustrator",
      "hosted_path": "dev/illustrator.svg",
      "url": "https://icons.d2lang.com/dev/illustrator.svg"
    },
    {
      "name": "inkscape",
      "label": "Inkscape",
      "hosted_path": "dev/inkscape.svg",
      "url": "https://icons.d2lang.com/dev/inkscape.svg"
    },
    {
      "name": "intellij",
      "label": "Intellij",
      "hosted_path": "dev/intellij.svg",
      "url": "https://icons.d2lang.com/dev/intellij.svg"
    },
    {
      "name": "ionic-original",
      "label": "Ionic Original",
      "hosted_path": "dev/ionic-original.svg",
      "url": "https://icons.d2lang.com/dev/ionic-original.svg"
    },
    {
      "name": "jasmine",
      "label": "Jasmine",
      "hosted_path": "dev/jasmine.svg",
      "url": "https://icons.d2lang.com/dev/jasmine.svg"
    },
    {
      "name": "java",
      "label": "Java",
      "hosted_path": "dev/java.svg",
      "url": "https://icons.d2lang.com/dev/java.svg"
    },
    {
      "name": "javascript",
      "label": "Javascript",
      "hosted_path": "dev/javascript.svg",
      "url": "https://icons.d2lang.com/dev/javascript.svg"
    },
    {
      "name": "jeet",
      "label": "Jeet",
      "hosted_path": "dev/jeet.svg",
      "url": "https://icons.d2lang.com/dev/jeet.svg"
    },
    {
      "name": "jetbrains",
      "label": "Jetbrains",
      "hosted_path": "dev/jetbrains.svg",
      "url": "https://icons.d2lang.com/dev/jetbrains.svg"
    },
    {
      "name": "jquery",
      "label": "Jquery",
      "hosted_path": "dev/jquery.svg",
      "url": "https://icons.d2lang.com/dev/jquery.svg"
    },
    {
      "name": "krakenjs",
      "label": "Krakenjs",
      "hosted_path": "dev/krakenjs.svg",
      "url": "https://icons.d2lang.com/dev/krakenjs.svg"
    },
    {
      "name": "laravel",
      "label": "Laravel",
      "hosted_path": "dev/laravel.svg",
      "url": "https://icons.d2lang.com/dev/laravel.svg"
    },
    {
      "name": "less",
      "label": "Less",
      "hosted_path": "dev/less.svg",
      "url": "https://icons.d2lang.com/dev/less.svg"
    },
    {
      "name": "linux",
      "label": "Linux",
      "hosted_path": "dev/linux.svg",
      "url": "https://icons.d2lang.com/dev/linux.svg"
    },
    {
      "name": "meteor",
      "label": "Meteor",
      "hosted_path": "dev/meteor.svg",
      "url": "https://icons.d2lang.com/dev/meteor.svg"
    },
    {
      "name": "mocha",
      "label": "Mocha",
      "hosted_path": "dev/mocha.svg",
      "url": "https://icons.d2lang.com/dev/mocha.svg"
    },
    {
      "name": "mongodb",
      "label": "Mongodb",
      "hosted_path": "dev/mongodb.svg",
      "url": "https://icons.d2lang.com/dev/mongodb.svg"
    },
    {
      "name": "moodle",
      "label": "Moodle",
      "hosted_path": "dev/moodle.svg",
      "url": "https://icons.d2lang.com/dev/moodle.svg"
    },
    {
      "name": "mysql",
      "label": "Mysql",
      "hosted_path": "dev/mysql.svg",
      "url": "https://icons.d2lang.com/dev/mysql.svg"
    },
    {
      "name": "nginx",
      "label": "Nginx",
      "hosted_path": "dev/nginx.svg",
      "url": "https://icons.d2lang.com/dev/nginx.svg"
    },
    {
      "name": "nodejs",
      "label": "Nodejs",
      "hosted_path": "dev/nodejs.svg",
      "url": "https://icons.d2lang.com/dev/nodejs.svg"
    },
    {
      "name": "nodewebkit",
      "label": "Nodewebkit",
      "hosted_path": "dev/nodewebkit.svg",
      "url": "https://icons.d2lang.com/dev/nodewebkit.svg"
    },
    {
      "name": "npm",
      "label": "Npm",
      "hosted_path": "dev/npm.svg",
      "url": "https://icons.d2lang.com/dev/npm.svg"
    },
    {
      "name": "oracle",
      "label": "Oracle",
      "hosted_path": "dev/oracle.svg",
      "url": "https://icons.d2lang.com/dev/oracle.svg"
    },
    {
      "name": "photoshop",
      "label": "Photoshop",
      "hosted_path": "dev/photoshop.svg",
      "url": "https://icons.d2lang.com/dev/photoshop.svg"
    },
    {
      "name": "php",
      "label": "Php",
      "hosted_path": "dev/php.svg",
      "url": "https://icons.d2lang.com/dev/php.svg"
    },
    {
      "name": "postgresql",
      "label": "Postgresql",
      "hosted_path": "dev/postgresql.svg",
      "url": "https://icons.d2lang.com/dev/postgresql.svg"
    },
    {
      "name": "postgresql-words",
      "label": "Postgresql Words",
      "hosted_path": "dev/postgresql-words.svg",
      "url": "https://icons.d2lang.com/dev/postgresql-words.svg"
    },
    {
      "name": "protractor",
      "label": "Protractor",
      "hosted_path": "dev/protractor.svg",
      "url": "https://icons.d2lang.com/dev/protractor.svg"
    },
    {
      "name": "pycharm",
      "label": "Pycharm",
      "hosted_path": "dev/pycharm.svg",
      "url": "https://icons.d2lang.com/dev/pycharm.svg"
    },
    {
      "name": "python",
      "label": "Python",
      "hosted_path": "dev/python.svg",
      "url": "https://icons.d2lang.com/dev/python.svg"
    },
    {
      "name": "rails",
      "label": "Rails",
      "hosted_path": "dev/rails.svg",
      "url": "https://icons.d2lang.com/dev/rails.svg"
    },
    {
      "name": "react",
      "label": "React",
      "hosted_path": "dev/react.svg",
      "url": "https://icons.d2lang.com/dev/react.svg"
    },
    {
      "name": "redhat",
      "label": "Redhat",
      "hosted_path": "dev/redhat.svg",
      "url": "https://icons.d2lang.com/dev/redhat.svg"
    },
    {
      "name": "redis",
      "label": "Redis",
      "hosted_path": "dev/redis.svg",
      "url": "https://icons.d2lang.com/dev/redis.svg"
    },
    {
      "name": "redux",
      "label": "Redux",
      "hosted_path": "dev/redux.svg",
      "url": "https://icons.d2lang.com/dev/redux.svg"
    },
    {
      "name": "ruby",
      "label": "Ruby",
      "hosted_path": "dev/ruby.svg",
      "url": "https://icons.d2lang.com/dev/ruby.svg"
    },
    {
      "name": "rust",
      "label": "Rust",
      "hosted_path": "dev/rust.svg",
      "url": "https://icons.d2lang.com/dev/rust.svg"
    },
    {
      "name": "safari",
      "label": "Safari",
      "hosted_path": "dev/safari.svg",
      "url": "https://icons.d2lang.com/dev/safari.svg"
    },
    {
      "name": "sass",
      "label": "Sass",
      "hosted_path": "dev/sass.svg",
      "url": "https://icons.d2lang.com/dev/sass.svg"
    },
    {
      "name": "scala",
      "label": "Scala",
      "hosted_path": "dev/scala.svg",
      "url": "https://icons.d2lang.com/dev/scala.svg"
    },
    {
      "name": "sequelize",
      "label": "Sequelize",
      "hosted_path": "dev/sequelize.svg",
      "url": "https://icons.d2lang.com/dev/sequelize.svg"
    },
    {
      "name": "sketch",
      "label": "Sketch",
      "hosted_path": "dev/sketch.svg",
      "url": "https://icons.d2lang.com/dev/sketch.svg"
    },
    {
      "name": "slack",
      "label": "Slack",
      "hosted_path": "dev/slack.svg",
      "url": "https://icons.d2lang.com/dev/slack.svg"
    },
    {
      "name": "sourcetree",
      "label": "Sourcetree",
      "hosted_path": "dev/sourcetree.svg",
      "url": "https://icons.d2lang.com/dev/sourcetree.svg"
    },
    {
      "name": "ssh",
      "label": "Ssh",
      "hosted_path": "dev/ssh.svg",
      "url": "https://icons.d2lang.com/dev/ssh.svg"
    },
    {
      "name": "stylus",
      "label": "Stylus",
      "hosted_path": "dev/stylus.svg",
      "url": "https://icons.d2lang.com/dev/stylus.svg"
    },
    {
      "name": "swift",
      "label": "Swift",
      "hosted_path": "dev/swift.svg",
      "url": "https://icons.d2lang.com/dev/swift.svg"
    },
    {
      "name": "symfony",
      "label": "Symfony",
      "hosted_path": "dev/symfony.svg",
      "url": "https://icons.d2lang.com/dev/symfony.svg"
    },
    {
      "name": "timescale",
      "label": "Timescale",
      "hosted_path": "dev/timescale.svg",
      "url": "https://icons.d2lang.com/dev/timescale.svg"
    },
    {
      "name": "tomcat",
      "label": "Tomcat",
      "hosted_path": "dev/tomcat.svg",
      "url": "https://icons.d2lang.com/dev/tomcat.svg"
    },
    {
      "name": "travis",
      "label": "Travis",
      "hosted_path": "dev/travis.svg",
      "url": "https://icons.d2lang.com/dev/travis.svg"
    },
    {
      "name": "trello",
      "label": "Trello",
      "hosted_path": "dev/trello.svg",
      "url": "https://icons.d2lang.com/dev/trello.svg"
    },
    {
      "name": "typescript",
      "label": "Typescript",
      "hosted_path": "dev/typescript.svg",
      "url": "https://icons.d2lang.com/dev/typescript.svg"
    },
    {
      "name": "ubuntu",
      "label": "Ubuntu",
      "hosted_path": "dev/ubuntu.svg",
      "url": "https://icons.d2lang.com/dev/ubuntu.svg"
    },
    {
      "name": "vagrant",
      "label": "Vagrant",
      "hosted_path": "dev/vagrant.svg",
      "url": "https://icons.d2lang.com/dev/vagrant.svg"
    },
    {
      "name": "vim",
      "label": "Vim",
      "hosted_path": "dev/vim.svg",
      "url": "https://icons.d2lang.com/dev/vim.svg"
    },
    {
      "name": "visualstudio",
      "label": "Visualstudio",
      "hosted_path": "dev/visualstudio.svg",
      "url": "https://icons.d2lang.com/dev/visualstudio.svg"
    },
    {
      "name": "vuejs",
      "label": "Vuejs",
      "hosted_path": "dev/vuejs.svg",
      "url": "https://icons.d2lang.com/dev/vuejs.svg"
    },
    {
      "name": "webpack",
      "label": "Webpack",
      "hosted_path": "dev/webpack.svg",
      "url": "https://icons.d2lang.com/dev/webpack.svg"
    },
    {
      "name": "webstorm",
      "label": "Webstorm",
      "hosted_path": "dev/webstorm.svg",
      "url": "https://icons.d2lang.com/dev/webstorm.svg"
    },
    {
      "name": "windows",
      "label": "Windows",
      "hosted_path": "dev/windows.svg",
      "url": "https://icons.d2lang.com/dev/windows.svg"
    },
    {
      "name": "wordpress",
      "label": "Wordpress",
      "hosted_path": "dev/wordpress.svg",
      "url": "https://icons.d2lang.com/dev/wordpress.svg"
    },
    {
      "name": "yarn",
      "label": "Yarn",
      "hosted_path": "dev/yarn.svg",
      "url": "https://icons.d2lang.com/dev/yarn.svg"
    },
    {
      "name": "yii",
      "label": "Yii",
      "hosted_path": "dev/yii.svg",
      "url": "https://icons.d2lang.com/dev/yii.svg"
    },
    {
      "name": "yunohost",
      "label": "Yunohost",
      "hosted_path": "dev/yunohost.svg",
      "url": "https://icons.d2lang.com/dev/yunohost.svg"
    },
    {
      "name": "zend",
      "label": "Zend",
      "hosted_path": "dev/zend.svg",
      "url": "https://icons.d2lang.com/dev/zend.svg"
    }
  ]
}

infrastructure

catalog.json 3.3 KB

{
  "schema_version": 1,
  "source": "https://icons.d2lang.com/",
  "storage_policy": "hosted-url-references-only",
  "requires_internet_to_render": true,
  "category": "infrastructure",
  "hosted_prefix": "infra",
  "icon_count": 17,
  "icons": [
    {
      "name": "001-access-denied",
      "label": "Access Denied",
      "hosted_path": "infra/001-access-denied.svg",
      "url": "https://icons.d2lang.com/infra/001-access-denied.svg"
    },
    {
      "name": "002-backup",
      "label": "Backup",
      "hosted_path": "infra/002-backup.svg",
      "url": "https://icons.d2lang.com/infra/002-backup.svg"
    },
    {
      "name": "003-firewall",
      "label": "Firewall",
      "hosted_path": "infra/003-firewall.svg",
      "url": "https://icons.d2lang.com/infra/003-firewall.svg"
    },
    {
      "name": "007-satellite",
      "label": "Satellite",
      "hosted_path": "infra/007-satellite.svg",
      "url": "https://icons.d2lang.com/infra/007-satellite.svg"
    },
    {
      "name": "010-data-sharing",
      "label": "Data Sharing",
      "hosted_path": "infra/010-data-sharing.svg",
      "url": "https://icons.d2lang.com/infra/010-data-sharing.svg"
    },
    {
      "name": "011-data-storage",
      "label": "Data Storage",
      "hosted_path": "infra/011-data-storage.svg",
      "url": "https://icons.d2lang.com/infra/011-data-storage.svg"
    },
    {
      "name": "011-delete",
      "label": "Delete",
      "hosted_path": "infra/011-delete.svg",
      "url": "https://icons.d2lang.com/infra/011-delete.svg"
    },
    {
      "name": "012-data",
      "label": "Data",
      "hosted_path": "infra/012-data.svg",
      "url": "https://icons.d2lang.com/infra/012-data.svg"
    },
    {
      "name": "013-transfer",
      "label": "Transfer",
      "hosted_path": "infra/013-transfer.svg",
      "url": "https://icons.d2lang.com/infra/013-transfer.svg"
    },
    {
      "name": "014-network",
      "label": "Network",
      "hosted_path": "infra/014-network.svg",
      "url": "https://icons.d2lang.com/infra/014-network.svg"
    },
    {
      "name": "019-network",
      "label": "Network",
      "hosted_path": "infra/019-network.svg",
      "url": "https://icons.d2lang.com/infra/019-network.svg"
    },
    {
      "name": "021-hardware",
      "label": "Hardware",
      "hosted_path": "infra/021-hardware.svg",
      "url": "https://icons.d2lang.com/infra/021-hardware.svg"
    },
    {
      "name": "022-hosting",
      "label": "Hosting",
      "hosted_path": "infra/022-hosting.svg",
      "url": "https://icons.d2lang.com/infra/022-hosting.svg"
    },
    {
      "name": "025-plug-in",
      "label": "Plug In",
      "hosted_path": "infra/025-plug-in.svg",
      "url": "https://icons.d2lang.com/infra/025-plug-in.svg"
    },
    {
      "name": "033-protection",
      "label": "Protection",
      "hosted_path": "infra/033-protection.svg",
      "url": "https://icons.d2lang.com/infra/033-protection.svg"
    },
    {
      "name": "040-global network",
      "label": "Global Network",
      "hosted_path": "infra/040-global network.svg",
      "url": "https://icons.d2lang.com/infra/040-global%20network.svg"
    },
    {
      "name": "041-tower",
      "label": "Tower",
      "hosted_path": "infra/041-tower.svg",
      "url": "https://icons.d2lang.com/infra/041-tower.svg"
    }
  ]
}

technology

catalog.json 3.7 KB

{
  "schema_version": 1,
  "source": "https://icons.d2lang.com/",
  "storage_policy": "hosted-url-references-only",
  "requires_internet_to_render": true,
  "category": "technology",
  "hosted_prefix": "tech",
  "icon_count": 21,
  "icons": [
    {
      "name": "009-cooler",
      "label": "Cooler",
      "hosted_path": "tech/009-cooler.svg",
      "url": "https://icons.d2lang.com/tech/009-cooler.svg"
    },
    {
      "name": "012-cpu-2",
      "label": "Cpu",
      "hosted_path": "tech/012-cpu-2.svg",
      "url": "https://icons.d2lang.com/tech/012-cpu-2.svg"
    },
    {
      "name": "014-cpu",
      "label": "Cpu",
      "hosted_path": "tech/014-cpu.svg",
      "url": "https://icons.d2lang.com/tech/014-cpu.svg"
    },
    {
      "name": "022-server",
      "label": "Server",
      "hosted_path": "tech/022-server.svg",
      "url": "https://icons.d2lang.com/tech/022-server.svg"
    },
    {
      "name": "041-joystick",
      "label": "Joystick",
      "hosted_path": "tech/041-joystick.svg",
      "url": "https://icons.d2lang.com/tech/041-joystick.svg"
    },
    {
      "name": "048-gamepad",
      "label": "Gamepad",
      "hosted_path": "tech/048-gamepad.svg",
      "url": "https://icons.d2lang.com/tech/048-gamepad.svg"
    },
    {
      "name": "052-smartphone-3",
      "label": "Smartphone",
      "hosted_path": "tech/052-smartphone-3.svg",
      "url": "https://icons.d2lang.com/tech/052-smartphone-3.svg"
    },
    {
      "name": "065-monitor-4",
      "label": "Monitor",
      "hosted_path": "tech/065-monitor-4.svg",
      "url": "https://icons.d2lang.com/tech/065-monitor-4.svg"
    },
    {
      "name": "069-hard-drive",
      "label": "Hard Drive",
      "hosted_path": "tech/069-hard-drive.svg",
      "url": "https://icons.d2lang.com/tech/069-hard-drive.svg"
    },
    {
      "name": "079-tablet-1",
      "label": "Tablet",
      "hosted_path": "tech/079-tablet-1.svg",
      "url": "https://icons.d2lang.com/tech/079-tablet-1.svg"
    },
    {
      "name": "antenna",
      "label": "Antenna",
      "hosted_path": "tech/antenna.svg",
      "url": "https://icons.d2lang.com/tech/antenna.svg"
    },
    {
      "name": "bar-chart",
      "label": "Bar Chart",
      "hosted_path": "tech/bar-chart.svg",
      "url": "https://icons.d2lang.com/tech/bar-chart.svg"
    },
    {
      "name": "bar-chart-1",
      "label": "Bar Chart",
      "hosted_path": "tech/bar-chart-1.svg",
      "url": "https://icons.d2lang.com/tech/bar-chart-1.svg"
    },
    {
      "name": "battery-1",
      "label": "Battery",
      "hosted_path": "tech/battery-1.svg",
      "url": "https://icons.d2lang.com/tech/battery-1.svg"
    },
    {
      "name": "browser-2",
      "label": "Browser",
      "hosted_path": "tech/browser-2.svg",
      "url": "https://icons.d2lang.com/tech/browser-2.svg"
    },
    {
      "name": "desktop",
      "label": "Desktop",
      "hosted_path": "tech/desktop.svg",
      "url": "https://icons.d2lang.com/tech/desktop.svg"
    },
    {
      "name": "diskette",
      "label": "Diskette",
      "hosted_path": "tech/diskette.svg",
      "url": "https://icons.d2lang.com/tech/diskette.svg"
    },
    {
      "name": "laptop",
      "label": "Laptop",
      "hosted_path": "tech/laptop.svg",
      "url": "https://icons.d2lang.com/tech/laptop.svg"
    },
    {
      "name": "power",
      "label": "Power",
      "hosted_path": "tech/power.svg",
      "url": "https://icons.d2lang.com/tech/power.svg"
    },
    {
      "name": "router",
      "label": "Router",
      "hosted_path": "tech/router.svg",
      "url": "https://icons.d2lang.com/tech/router.svg"
    },
    {
      "name": "servers",
      "label": "Servers",
      "hosted_path": "tech/servers.svg",
      "url": "https://icons.d2lang.com/tech/servers.svg"
    }
  ]
}

README.md 2.3 KB

# Hosted D2 icon URL catalogs

These resources index the **Development**, **Technology**, and **Infrastructure** categories published at [icons.d2lang.com](https://icons.d2lang.com/).

## Storage policy

This directory contains URL metadata only. It deliberately does **not** contain or redistribute SVG bytes.

- `development/catalog.json` maps the hosted `dev/` category.
- `technology/catalog.json` maps the hosted `tech/` category.
- `infrastructure/catalog.json` maps the hosted `infra/` category.
- Each entry provides a display label, hosted path, and HTTPS URL suitable for a D2 `icon:` property.
- Together, the three catalogs are the exact hosted-icon allowlist. Select an
  existing `url` value; do not guess filenames or manually add unlisted URLs.

## Runtime requirement

Rendering a D2 diagram that uses these URLs requires outbound internet access to `https://icons.d2lang.com`. Syntax validation does not prove that a remote icon is reachable. During a complete render, D2 fetches the selected SVG and embeds it into the canonical output, leaving the resulting `architecture.svg` self-contained.

Example:

```d2
runtime: Application runtime {
  icon: https://icons.d2lang.com/dev/python.svg
}
```

Do not rewrite catalog entries as local SVG paths unless the project separately approves vendoring and redistribution of the corresponding assets.

## Licensing and trademarks

The D2 documentation describes the hosted collection as free for convenience, but the catalog does not publish one blanket redistribution license or provenance manifest for all assets. Some entries depict third-party products or trademarks and may be governed by their owners' terms.

These catalogs are references to the hosted service, not a grant of rights. Use an icon only for accurate identification in an architecture diagram, do not imply endorsement, and review applicable brand or usage policies when necessary.

## Refreshing the catalogs

From the query-engine package directory:

```bash
uv run python scripts/update_d2_icon_catalog.py
```

The updater fetches only the public catalog index (or reads `--source-file`) and writes deterministic URL-only JSON; it never downloads linked SVG assets. Review additions and removals before committing an update.

## Official references

- [D2 icons and images](https://d2lang.com/tour/icons/)
- [D2 hosted icon catalog](https://icons.d2lang.com/)

SKILL.md 12.7 KB

---
name: architecture-diagrams
description: >-
  Author and visually review evidence-based software architecture diagrams as
  D2 v0.7.1 source rendered with ELK to canonical SVG.
---

# D2 Architecture Diagrams

Use this guide to create or review the repository architecture from current,
explicit evidence. The diagram must answer one architectural question clearly;
it is not an exhaustive code inventory.

This skill contains authoring guidance and URL-only icon catalogs. It has no
executable skill scripts. Runtime artifact ownership, console tools, and the
`validate_architecture` finish rule are defined by the agent instructions—follow
those for what you may write and which tools to call. This skill defines how to
author and visually approve `architecture.d2`.

## Source format and render expectations

- Author unfenced D2 only in `architecture.d2`. Do not wrap the source in a
  Markdown document or code fence.
- Target **D2 v0.7.1 with ELK**. The validator owns syntax checks, version
  enforcement, rendering, atomic `architecture.svg` replacement, and digests.
- The only persisted render is SVG. The validator may attach a temporary visual
  preview of the exact generated SVG for review; that preview is not a
  repository artifact and must not be written into the repo.
- Do not judge final layout from D2 source alone. Inspect the validator preview
  against the checklists in this skill. Any source edit after a successful
  validation requires another validate + visual review (see agent finish rule
  and §8 below).

## 1. Build an evidence inventory first

Read every explicitly listed, fresh `app_interfaces.md` artifact. Consult only
the minimal source, configuration, deployment, or infrastructure evidence
needed to confirm a claim. Do not use stale or unlisted interface artifacts and
do not invent components, protocols, dependencies, ownership, or deployment
boundaries.

Before writing D2, record a concise inventory:

- **Nodes:** actors, entry points, deployable applications and services, data
  stores, queues, and external systems.
- **Boundaries:** supported ownership, deployment, trust, network, or subsystem
  boundaries.
- **Relationships:** source, target, semantic direction, action label, and
  interaction type.
- **Scope:** the primary question, abstraction level, and deliberate omissions.
- **Visual vocabulary:** the meaning of shapes, colors, line patterns, and
  icons.

Treat the relationship inventory as a non-regression checklist. Layout or style
changes must never silently remove, merge, reverse, or mislabel an interaction.
Co-location in a deployment file proves membership, not communication.

Model independently meaningful runtime nodes. Omit package directories, shared
source modules, and library-only codebases unless the chosen architectural
question specifically concerns components inside one runtime.

## 2. Keep one abstraction level

Choose one primary level and architectural question:

- **Context:** people and external systems around the system.
- **Container:** independently deployable applications, services, and stores.
- **Component:** important modules inside one application or service.
- **Deployment:** runtime nodes, environments, networks, and infrastructure.
- **Data flow:** production, transformation, persistence, and consumption.

Do not combine all levels in one image. Prefer a focused system-level diagram;
if multiple views are truly required, use D2 boards or composition rather than
crowding unrelated detail together.

Responsibility-oriented container groupings often include consumers and entry
points, repository-owned backend services, platform/infrastructure, and
external services. Create only evidence-backed, non-empty groups. These roles
are useful organization aids, not mandatory decorative boxes.

## 3. Use stable keys and meaningful containers

Separate machine-friendly keys from reader-facing labels. Relationships must
reference keys, including qualified keys across containers:

```d2
client_tier: Client tier {
  web_app: Web application
}

service_tier: Service tier {
  order_api: Order API
}

client_tier.web_app -> service_tier.order_api: submit order
```

Use lower-case stable keys that survive label changes. Keep labels concise and
specific. Use containers only when they communicate ownership, deployment,
trust, runtime, network, or internal/external responsibility. Keep nesting
shallow unless another level adds architectural meaning.

## 4. Establish topology before styling

Add nodes, boundaries, and evidence-backed relationships before colors, icons,
or spacing controls. Select one global direction from the dominant reading
order:

```d2
direction: right

users -> web_app: send requests
web_app -> api: call API
api -> worker: enqueue job
worker -> database: persist result
```

Use `right` when the dominant flow is users → application → dependencies. Use
`down` when it is entry points → processing → persistence. ELK is hierarchical:
nested containers do not have independent flow directions. Render promising
global directions rather than judging layout from source alone.

Declare the dominant semantic flow in the chosen reading direction when
possible. Keep edge labels short, action-oriented, and evidence-backed, such as
`send request`, `publish event`, `read profile`, or `persist result`. Avoid
endpoint-name repetition and prose paragraphs on edges.

Preserve the true semantic arrow direction. If available evidence establishes a
relationship but not direction, do not invent one.

### Reverse and feedback flows

First render the semantically direct edge:

```d2
notification_service -> web_app: send live update
```

A literal reverse edge can create a large loop in a layered layout. Only when it
materially damages readability may you declare the edge in the layout direction
and place the visible arrowhead at its source:

```d2
# Ranked forward for ELK; the visible arrow still points to web_app.
web_app -> notification_service: send live update {
  source-arrowhead: {
    shape: triangle
  }
  target-arrowhead: {
    shape: none
  }
}
```

Use this workaround sparingly. Add an explanatory source comment, inspect the
rendered arrowhead, confirm the visible direction is semantically correct, and
prefer the direct edge whenever its layout is acceptable.

## 5. Define a small semantic visual language

Use a few reusable classes rather than duplicating attributes. Useful edge
semantics are synchronous request, asynchronous event/work, data access or
replication, and external integration:

```d2
classes: {
  service: {
    style: {
      border-radius: 8
      shadow: true
    }
  }
  request: {
    style: {
      stroke: "#2563EB"
      stroke-width: 2
    }
  }
  event: {
    style: {
      stroke: "#7C3AED"
      stroke-width: 2
      stroke-dash: 4
    }
  }
  data: {
    style: {
      stroke: "#B45309"
      stroke-width: 2
    }
  }
  external: {
    style: {
      stroke: "#047857"
      stroke-width: 2
    }
  }
}

api: API {class: service}
worker: Worker {class: service}
api -> worker: publish task {class: event}
```

These colors are examples, not required choices. Meaning must never depend on
color alone: combine color with an action label, dash pattern, arrow style, or
shape. Use object-level overrides only for intentional exceptions.

Keep styling restrained: light container fills, clear borders, consistent leaf
styles, modest rounding or shadows, and hierarchy-appropriate font sizes. Avoid
a unique color or shape for every node. Maintain sufficient contrast and text
size at the expected documentation scale.

## 6. Use only exact catalog icon URLs

Icons are optional recognition aids, not a type system or a substitute for text.
Use them mainly on recognizable leaf nodes such as a database, language, cloud
service, or external product. Prefer a labeled node with an icon; use
`shape: image` only when an icon-only element is genuinely appropriate.

Before adding an icon, call `read_skill_resource` with skill name
`architecture-diagrams` and one of these exact resource names:

- `icons/development/catalog.json` for hosted `dev/` icons
- `icons/technology/catalog.json` for hosted `tech/` icons
- `icons/infrastructure/catalog.json` for hosted `infra/` icons
- `icons/README.md` for storage, runtime, licensing, and refresh policy

Use only an exact HTTPS `url` from a packaged catalog. Never guess a filename,
use an arbitrary host, use a local icon path, or copy and redistribute hosted
SVG bytes. Keep labels beside icons, avoid product logos on broad subsystem
containers, and use a coherent family where practical.

```d2
database: Application database {
  icon: https://icons.d2lang.com/dev/postgresql.svg
}
```

Hosted icons require outbound access to `https://icons.d2lang.com` during the
complete D2 render. Validation alone does not prove reachability. D2 embeds the
fetched icon in the final SVG, so that rendered artifact is self-contained.
If the renderer has no internet access, omit the icon or use a built-in D2 shape
instead of creating a broken reference. Re-render after adding icons because
they change node dimensions and routing.

The catalogs are URL metadata, not a blanket license or trademark grant. Use
third-party marks only for accurate identification, do not imply endorsement,
and follow applicable brand and usage policies.

## 7. Tune spacing last

Wait until nodes, boundaries, relationships, direction, classes, and icons are
stable. Then adjust one concern at a time:

- Increase layer spacing when edge labels are cramped.
- Increase edge-to-node spacing when routes pass too close to nodes.
- Increase container padding when children crowd borders or titles.
- Reduce spacing carefully when the composition is unnecessarily large.

Do not copy unknown ELK flags from another D2 release. The validator controls
the canonical v0.7.1 render. Prefer simple source-level topology and direction
changes; request validator changes separately if a canonical ELK option is
truly required.

## 8. Validate, inspect, and revise

Use this sequence:

1. Build and check the node, boundary, relationship, scope, and vocabulary
   inventory.
2. Choose one abstraction level and one global reading direction.
3. Author the unstyled topology in `architecture.d2`.
4. Correct hierarchy and feedback-flow problems without changing semantics.
5. Add small semantic classes and restrained styling.
6. Load exact icon catalogs and add only useful icons.
7. Tune spacing one concern at a time.
8. Re-read the complete D2 source and compare it with the evidence inventory.
9. Call `validate_architecture` with no arguments.
10. Inspect the attached temporary preview of the exact canonical SVG at full
    resolution and expected embedded size.
11. Repair every structural or visual issue, then re-read, revalidate, and
    inspect again.
12. Load this skill again for final review. Finish only when the latest source
    and render digests correspond to the visually approved artifacts.

Compilation is necessary but not visual approval. Reject a render with
unnecessary crossings, overlapping edges, routes through nodes or labels,
ambiguous label association, excessive bends, dominant reverse-flow loops,
cluttered boundaries, or unreadable text. Never remove or reverse an
architecture fact merely to improve layout.

### Correctness and non-regression

- [ ] Every in-scope node and meaningful boundary is present.
- [ ] Every required relationship remains present and correctly labeled.
- [ ] Visible arrowheads point in the true semantic direction.
- [ ] Containers represent real boundaries rather than decoration.
- [ ] The final topology still matches the evidence inventory.
- [ ] No unsupported component, protocol, dependency, or ownership claim was
      introduced.

### Readability

- [ ] The primary reading order is immediately apparent.
- [ ] Edge labels associate clearly with their relationships.
- [ ] Crossings, bends, and feedback loops are limited.
- [ ] Text remains readable at documentation size.
- [ ] Classes have consistent meanings.
- [ ] Icons improve recognition without replacing labels.

### Accessibility

- [ ] Meaning does not depend only on color.
- [ ] Container fills, borders, labels, and edges have sufficient contrast.
- [ ] Fonts are legible at the intended size.
- [ ] Unfamiliar icons have accompanying text.

## Official references

- [D2 introduction](https://d2lang.com/tour/intro/)
- [D2 containers](https://d2lang.com/tour/containers/)
- [D2 connections and arrowheads](https://d2lang.com/tour/connections/)
- [D2 classes](https://d2lang.com/tour/classes/)
- [D2 styles](https://d2lang.com/tour/style/)
- [D2 icons and images](https://d2lang.com/tour/icons/)
- [D2 layout overview](https://d2lang.com/tour/layouts/)
- [D2 ELK layout](https://d2lang.com/tour/elk/)
- [D2 ELK example gallery](https://d2lang.com/examples/elk/)
- [Eclipse ELK option reference](https://www.eclipse.org/elk/reference.html)
- [D2 hosted icon catalog](https://icons.d2lang.com/)