plantuml-stdlib, the sprite and macro library behind PlantUML diagrams

A standard library, in the C sense

The name is the concept. plantuml-stdlib is the standard library for PlantUML, and the project states the analogy directly, following the C convention for the C standard library. The analogy is instructive because it explains the whole design.

A C program does not bundle the C library. It includes headers that declare functions, and the implementation comes from the platform. In the same way, a PlantUML diagram does not draw AWS service icons because PlantUML has them built in. It includes a library that defines the sprites and macros, and the actual implementation comes from the standard library collection, which is distributed separately and versioned separately.

The practical consequence is that a diagram is not portable by itself. The source says `!include <aws/common>` and the include resolves against whatever standard library the renderer has, whether that is the official PlantUML release, the web editor at plantuml.com, or a self-hosted jar. If the renderer does not have that library, the diagram fails to render or falls back to a plain shape.

That is exactly why the project is set up the way it is. The documentation states that this Standard Library is included in the official release of PlantUML, so anyone using a standard PlantUML distribution already has it. The repository here is where the contents are authored and built, not something you normally install separately.

The audience is two groups. The first is the diagram author who wants icons and macros that look right without maintaining a private asset repository. The second is the contributor who adds or updates a library, and the build tooling in this repository exists for that job.

The catalogue: icon sets and macro libraries

The table of contents in the project documentation is effectively the inventory, and it separates into two families.

The icon sets are the most familiar. The Amazon Web Services section covers AWS Icons, the AWS library `aws`, and the Amazon Labs AWS Library `awslib`. There is an Azure library `azure`, a Google Cloud Platform library `gcp`, a K8s library `k8s`, Bootstrap Icons `bootstrap`, and the Google icon set under three names, `material`, `material2` and `material7`, where the older PNG sprite entries are kept for compatibility and the SVG sprites are the newer ones.

The macro libraries are the other family, and they are where the modelling languages live. There is the C4 library `C4`, which is the C4-PlantUML extension, and a Classy library `classy` with a Classy C4 variant `classy-c4`. The Domain Story library `DomainStory` covers the DomainStory-PlantUML notation. Edgy Enterprise Design `edgy` comes with its own facets, elements and links vocabulary. EIP-PlantUML is `eip`, the Elastic library is `elastic`, and Tupadr3 is `tupadr3`, the third-party icon set that many PlantUML users know from the Font Awesome and Devicon style sprites.

AdaML `adaml` is the most unusual of the set, and the documentation explains it well. It is UML tailored for the Ada 2012 programming language, a modeling language to draw UML diagrams implemented in PlantUML, and an easy way to learn Ada through the use of UML and object-oriented concepts. Its feature list mentions UML tailored to show particular Ada language characteristics, a coherent set of functions for designing software components for Ada, high quality drawings in ps and eps that are easy to embed in other documents, and ease of learning by example.

The ArchiMate library is the best documented of the ordinary entries. It describes ArchiMate as an enterprise architecture modeling language supporting the description, analysis and visualization of architecture across business domains, and notes that its features cover all ArchiMate 3.2 types and relationships, regular shapes as rectangles with graphical stereotype icons plus special shapes for stakeholders, roles, actors, value and meaning, and arbitrary nesting of concepts.

Including a library is one line, and the theme is commented out

The AdaML example in the documentation shows the whole usage pattern, and it is worth reading because the shape of the API is obvious from it.

@startuml
!include <AdaML/AdaML>

actor User
agent String_Instrument
agent Screen
agent Touch_Screen
agent Microphone

begin_package_spec("Floyd_Tuner")

  subprogram("Main")

  package("View")
  package("Controller")
  package("Signal_Analyzer")
  package("Sample_Collector")

  depends("User", "Touch_Screen", "interacts >")
  depends("Main", "Controller", "starts >")
  depends("User", "Screen", "see")
  depends("User", "String_Instrument", "plays\n&\ntunes")

  depends("Touch_Screen", "Controller", "commands")

  depends("Controller", "Sample_Collector", "manages")
  depends("Controller", "Signal_Analyzer", "configures")
  depends("Controller", "View", "commands")

  depends("View", "Screen", "output >")
  depends("View", "Signal_Analyzer", "read\nresults >")
  depends("Signal_Analyzer", "Sample_Collector", "read\nsamples >")
  depends("Sample_Collector", "Microphone", "ADC")

  depends("String_Instrument", "Microphone", "captures <")

end()
@enduml

One line does the work. `!include <AdaML/AdaML>` pulls in the library, and after that the diagram uses the vocabulary it defines: `begin_package_spec`, `subprogram`, `package`, `depends` with a relationship label and an arrow direction, and a matching `end()` to close the block. The `>` and `<` suffixes on the relationship strings are direction markers, and the ` ` inside a label is a line break in the rendered text.

The ArchiMate example shows the same idea with a different notation, and it also shows the theme mechanism. After the include there is a set of `!theme` lines, each commented out.

@startuml Internet Browser Sample

!include <archimate/Archimate>
'!theme archimate-alternate from <archimate/themes>
'!theme archimate-handwriting from <archimate/themes>
'!theme archimate-lowsaturation from <archimate/themes>
'!theme archimate-saturated from <archimate/themes>
'!theme archimate-standard from <archimate/themes>

So a library can ship themes alongside its macros, in a `themes` subfolder, and the diagram author picks one by uncommenting a line. The layout directives `LAYOUT_AS_SKETCH()`, `LAYOUT_LEFT_RIGHT()` and `LAYOUT_TOP_DOWN()` are commented out in the same way, because they are global layout choices rather than part of the notation.

The comment character being a single quote, not a double slash, is the PlantUML convention and it is worth knowing before you write a diagram and wonder why the line is being rendered.

The Google icon set comes in two generations

The Google icon entries are worth a separate look because they show how this library handles versioning inside a name.

The documentation lists the old version PNG sprites under a heading that marks them as compatibility mode, covering `material` and `material2`, and the SVG sprites under `material7` and `material7.4.47`. The compatibility note in the table of contents is a sub-section of the Google icon entry, which tells you the old PNG sprites are kept for diagrams that have not been updated, while the SVG sprites are the current path.

The entry names carry a version. `material7.4.47` is a name, not a directory listing, and the fact that the library exposes several aliases of the same family under different names is a deliberate compatibility decision rather than an accident. A diagram that says `!include <material2/common>` keeps working after the library reorganised its sprites, and a new diagram can use the SVG set.

The Google icon entry is also the one with a documented mechanism for macros and predefined values, via an include of `material7/common`. That tells you the standard libraries cover more than sprite collections. A library can ship a set of named constants and helper macros, and a diagram can pull in just that part of the library with a path pointing at the specific file inside it, rather than the whole thing.

For an author this is the interesting part of the design. The library is a namespace of include paths, and what you include can be a whole notation, a single common file, a theme, or a set of sprites. The cost of that flexibility is that a diagram's includes are a real dependency list, and a change in the library can change what a diagram renders.

That last point is the tension in the whole project. A standard library that ships with the renderer is convenient and consistent, but it also means your diagram inherits whatever the current library version does.

How the library is built and what the repository holds

The repository is a Gradle project, and the layout shows what a standard library collection actually contains.

The top-level entries are a `stdlib/` directory, which is the library content itself, a `src/` directory, a `script/` directory, an `output/` directory, `build.gradle.kts` with `settings.gradle`, the Gradle wrapper in both `gradlew` and `gradlew.bat` form, and a `gradle/` directory for the wrapper jar and properties. There is a `CONTRIBUTING.md`, a `.gitattributes` file, and a `.github/` directory for the workflows.

The presence of `src/` alongside `stdlib/` is the thing to note. A standard library holds more than assets. It contains macro definitions, and in PlantUML those can be written as C4-style sprite references or as preprocessor code. The `src/` directory is where the building blocks that the `stdlib/` content is generated or assembled from live, and `script/` holds the automation that turns them into the shipped layout.

The `output/` directory is the build product, and it is checked into the tree rather than ignored, which fits a project whose output is consumed by a downstream release process that packages the library into the PlantUML distribution.

The build system being Gradle with a Kotlin DSL and a wrapper means a contributor needs a JDK and nothing else, and the same build runs on any platform, which matters when the output has to be identical everywhere.

There are no GitHub releases for this repository. The distribution model is the PlantUML release itself, so there is no separate version stream to track here. The last push to the repository was on 2026-10-06, which is recent enough that the library is being actively worked on, and the project is not archived.

On licensing, the honest statement is that this repository does not carry a licence file of its own. The top-level listing has no LICENSE entry, and the licence field is not classified. The artwork in a sprite library has its own provenance, since some icon sets carry their own terms, so anyone redistributing a derived collection needs to check the terms of the individual icon sets rather than assume one blanket licence covers the repository.

What a standard library costs you in control

There is a real trade-off in this project, and it is the reason to think before depending on the standard library for a long-lived diagram set.

The benefit is consistency. A diagram that includes `<aws/common>` renders identically in the PlantUML web editor, in a local jar, and in whatever CI image your team uses, because the standard library ships with the release. You do not manage sprites, you do not mirror an asset repository, and you do not get an outage when someone moves a file.

The cost is that the library moves on PlantUML's schedule rather than yours. When the Google sprites were reorganised from PNG to SVG, the library kept the old names as compatibility aliases, and that is the kind of decision that keeps old diagrams alive. But it is a decision made upstream, and it applies to the whole set. If a diagram in your documentation set depends on a specific icon rendering, that rendering is not under your control once you accept the standard library.

The second cost is that a standard library is a moving target for a different reason: the availability of a library is a function of the PlantUML version you run. A diagram referencing a library that only exists in a newer release will not render on an older jar, and a CI image pinned to an old PlantUML will silently lose it. Since this repository has no releases of its own, the version you get is the version bundled in whichever PlantUML you install.

The third cost is the one the format makes hard to avoid. Because the library is referenced by name and resolved by the renderer, a diagram is not self-contained. If you need a diagram to render identically for a decade, in an archived PDF, on a customer's server, a self-contained diagram with embedded images is a better fit than an include.

None of this makes the standard library a bad choice. For the common case, a diagram in a repository that renders in CI today, the consistency argument wins clearly. The design is right for the problem, and the trade-off only bites in the corners.

Editorial conclusion

plantuml-stdlib suits anyone who draws architecture diagrams with PlantUML and wants correct vendor icons and reusable macros without maintaining a private sprite repository, and it is the thing to depend on when you want your diagrams to keep rendering the same way PlantUML itself renders them. It does not suit a team that needs a specific icon set version pinned, since the library tracks the PlantUML release cycle, and it does not suit a project that needs an unreleased or custom library, because the contents are curated upstream. Verify first that the icons your diagram needs exist in the set you are on, that the macro library you plan to use has the elements your diagram requires rather than a close approximation, and that the way you consume the library in CI is unaffected by when the bundled version changes.

Frequently asked questions

Official sources

1. Issues
2. plantuml/plantuml-stdlib on GitHub
3. Project website
4. README