What are UML diagrams?

UML diagrams are standardized visual models of a software system. UML stands for Unified Modeling Language, a shared set of shapes, lines and rules for drawing how a system is structured and how it behaves, so that anyone who knows the notation can read the diagram the same way.

A UML diagram might show the classes in a codebase and how they relate, the messages two services exchange during a login, the states an order passes through from "placed" to "delivered," or the actions a user can take in an app. Different diagram types answer different questions, but they all share one vocabulary.

That shared vocabulary is the point. Before UML, every team drew boxes and arrows a little differently, and every diagram needed a legend. UML, created in the mid-1990s by Grady Booch, Ivar Jacobson and James Rumbaugh and standardized by the Object Management Group in 1997, gave software teams a common language.

Today it's used for designing systems, documenting them, onboarding engineers and communicating with non-technical stakeholders.

Why use UML diagrams?Copied!Link to this section

They make architecture visible. A class diagram or component diagram shows the whole shape of a system on one page, something no amount of reading code will give you quickly.
They catch design problems early. Drawing a sequence diagram before writing code exposes missing steps, circular dependencies and unclear ownership while they're still cheap to fix.
They're a common language. Because the notation is standard, a diagram drawn by one engineer reads the same to another, or to a PM, a QA lead or a new hire.
They document intent, not just implementation. Code tells you what a system does; a UML diagram tells you what it was meant to do and why.
They scale down. You don't need the full formal notation to get value. A rough class diagram on a whiteboard is still a UML diagram.

Types of UML diagramsCopied!Link to this section

UML defines 14 diagram types, split into two families. In practice, most teams use five or six regularly.

Structural diagrams: what the system isCopied!Link to this section

Structural diagrams show the static parts of a system and how they relate.

Class diagram. The most widely used UML diagram. Each box is a class with its attributes and methods; lines between boxes show inheritance, association, aggregation and composition. Use it to design or document an object model or database schema. Start from the UML class diagram template →

Component diagram. Shows the high-level pieces of a system (services, libraries, modules) and the interfaces between them. Good for architecture overviews.

Deployment diagram. Maps software components onto the hardware or infrastructure they run on: servers, containers, devices, networks.

Object diagram. A snapshot of specific instances of classes at one moment in time. Useful for explaining a tricky data scenario.

Package diagram. Groups classes into packages or namespaces and shows dependencies between them.

Composite structure and profile diagrams round out the family but are rarely used outside formal modeling.

Behavioral diagrams: what the system doesCopied!Link to this section

Behavioral diagrams show how the system acts over time and how its parts interact.

Use case diagram. Shows the actors (users, external systems) and the goals they can accomplish with the system. It's the "who can do what" view, ideal for scoping a product or feature. Start from the UML use case diagram template →

Sequence diagram. Shows how objects or services exchange messages over time: each participant gets a vertical lifeline, and horizontal arrows show calls and responses in order. The go-to diagram for API flows, authentication and any multi-step interaction. Start from the UML sequence diagram template →

Activity diagram. UML's version of a flowchart: actions, decisions, parallel branches and merges that describe a workflow or algorithm. Use it for business processes and the logic inside a single operation. Start from the UML activity diagram template →

State machine diagram. Shows the states an object can be in and the events that move it between them, such as an order going from Pending to Paid to Shipped, or a UI component going from Idle to Loading to Error. Start from the UML state diagram template →

Communication, timing and interaction overview diagrams are more specialized variants of the above.

Which one to reach for: if you're explaining structure, start with a class diagram. If you're explaining a process, start with a sequence diagram (for interactions between parts) or an activity diagram (for the steps themselves). Use case diagrams belong at the very start of a project; state diagrams whenever something has a lifecycle.

UML diagram symbols: a cheat sheetCopied!Link to this section

Each diagram type has its own notation, but a small set of symbols covers most of what you'll draw.

Symbol	Looks like	Meaning
Class	Rectangle split into 3 sections	Name / attributes / methods
Actor	Stick figure	A user or external system
Use case	Oval	A goal an actor can achieve
Object / lifeline	Rectangle with a dashed vertical line	A participant in a sequence diagram, over time
Message	Solid arrow (sync) or open-headed arrow (async)	A call between participants; dashed arrow = return
Activation bar	Thin rectangle on a lifeline	The participant is doing work
State	Rounded rectangle	A condition an object can be in
Initial / final state	Filled circle / filled circle in a ring	Where a lifecycle starts and ends
Action	Rounded rectangle (activity diagram)	A step in a workflow
Decision / merge	Diamond	A branch or rejoin in flow
Fork / join	Thick horizontal bar	Parallel paths split or rejoin
Association	Plain line	Two classes are related
Inheritance	Line with hollow triangle	"Is a": a subclass extends a superclass
Aggregation	Line with hollow diamond	"Has a": a whole made of parts that can exist alone
Composition	Line with filled diamond	"Owns a": parts that don't exist without the whole
Dependency	Dashed arrow	One element uses another
Multiplicity	`1`, `0..1`, ``, `1..` at line ends	How many instances relate

Whimsical's shape and connector libraries cover all of these: class boxes with sections, ovals and stick-figure icons, diamonds and pill shapes, and connector endpoints for arrows, hollow and filled diamonds, triangles and the 0..1 / 1..* multiplicity markers used in class diagrams.

UML diagram promptsCopied!Link to this section

The fastest way to get a first draft is to describe the system in plain language and let Whimsical AI draw it. Copy any of these prompts, swap in your own names, and paste it into Whimsical AI.

Class diagramCopied!Link to this section

Create a UML class diagram for an e-commerce app with the classes Customer, PremiumCustomer, Order, OrderLine and Product. PremiumCustomer inherits from Customer. A Customer has many Orders. An Order is composed of OrderLines. Each OrderLine references one Product. Show attributes, methods and multiplicity.

Sequence diagramCopied!Link to this section

Create a UML sequence diagram for user login with the participants Browser, API, Auth Service and Database. Browser sends POST /login to API. API calls validate(credentials) on Auth Service. Auth Service calls findUser(email) on Database and gets the user back. Auth Service returns a token to API. API returns 200 OK with the token to Browser. Add an alternative path for an invalid password that returns 401.

Use case diagramCopied!Link to this section

Create a UML use case diagram for a project management app. Actors: Team Member, Admin and Billing System. Use cases: Create task, Assign task, Comment on task, Invite member and Manage subscription. Team Member can do the first three. Admin can do everything. Manage subscription connects to the Billing System.

Activity diagramCopied!Link to this section

Create a UML activity diagram for a pull request review. Start with Open PR. Run lint and tests in parallel, then join. Decision: CI passed? If no, fix and push, then loop back to running CI. If yes, request review. Decision: approved? If no, address comments and loop back to request review. If yes, merge and deploy, then end.

State diagramCopied!Link to this section

Create a UML state diagram for a support ticket. States: New, Open, Pending, Resolved, Closed and Reopened. New goes to Open on assign. Open goes to Pending when awaiting the customer, and back to Open on customer reply. Open goes to Resolved on fix. Resolved goes to Closed after 7 days. Closed goes to Reopened if the customer replies, and Reopened goes back to Open.

Tip: name the diagram type, list the elements, then describe the relationships one per sentence. The more literal the prompt, the closer the first draft. You can always refine by hand afterwards.

How to make a UML diagram in WhimsicalCopied!Link to this section

Whimsical is built for exactly this kind of diagramming: fast enough to sketch in a design review, precise enough to document with.

Choose the diagram type. Ask what question the diagram answers: structure (class), interaction (sequence), process (activity), scope (use case) or lifecycle (state).
Start from a template, or a blank board. The fastest route is one of the UML templates: activity diagram, class diagram, use case diagram, state diagram or sequence diagram. Each opens with the right shapes and notation already in place; replace the placeholder text with your own.
Add elements with quick-add. Hover any shape and click the arrow on a side to create a new, already-connected shape. For class diagrams, duplicate a class box and edit its sections; for use case diagrams, drop in actor icons and ovals.
Set connector endpoints. Select a connector and change its start and end markers: arrow, hollow triangle for inheritance, hollow or filled diamond for aggregation and composition, or none. Switch to a dashed line for dependencies and return messages.
For sequence diagrams, use the dedicated tool. Whimsical's sequence diagram tool lays out lifelines and messages for you: add participants, then type messages in order and the diagram builds itself, with activation bars and return arrows handled automatically. Reordering a message is a drag.
Label relationships. Add multiplicity (1, *, 0..1) at connector ends and role names along lines. Use text labels on messages in sequence diagrams.
Group and color. Put related classes in a section, color-code layers (UI, domain, data) or teams, and add a short legend if you introduce anything non-standard.
Share and keep it alive. Send the board link, collect comments on specific elements, and update the diagram as the system changes. Embed it in your docs or Notion so it stays next to the code it describes.

Generate from text. Describe the system in plain language, such as "a class diagram for a library with Books, Members and Loans," and Whimsical AI drafts the diagram for you to refine. Whimsical also accepts Mermaid syntax, so if you already write classDiagram or sequenceDiagram blocks in your docs, paste them in and get an editable board.

Tips for better UML diagramsCopied!Link to this section

One question per diagram. If a diagram tries to show structure and behavior, split it.
Show only what matters. Omit getters, setters and trivial attributes from class diagrams. Readers need the shape, not every field.
Keep the notation standard where it counts. Inheritance triangles, composition diamonds and message arrows carry meaning, so don't improvise those. Everything else can be relaxed.
Name things exactly as they are in code. OrderService, not "the order thing." Diagrams that match the codebase stay useful.
Diagram the happy path first, then add the failure branches that actually matter.
Date it or link it. A diagram that lives in Whimsical and is linked from the README is far more likely to be kept current than a PNG in a slide deck.

Frequently asked questionsCopied!Link to this section

What is a UML diagram?Copied!Link to this section

A standardized visual model of a software system, drawn using the Unified Modeling Language notation. It can show structure (classes, components) or behavior (interactions, workflows, states).

What are the main types of UML diagrams?Copied!Link to this section

Fourteen in total, split into structural (class, component, deployment, object, package and others) and behavioral (use case, sequence, activity, state machine and others). Class, sequence, use case, activity and state diagrams are the most common.

What is UML used for?Copied!Link to this section

Designing software before it's built, documenting systems that exist, communicating architecture across teams and onboarding engineers.

Is a flowchart a UML diagram?Copied!Link to this section

Not exactly. UML's activity diagram is closely related to a flowchart and uses similar shapes, but it follows UML's formal notation and adds concepts like parallel forks and swimlanes.

Do I need to know all of UML to use it?Copied!Link to this section

No. Most teams use a handful of diagram types and a small subset of the notation. Start with the symbols in the cheat sheet above.

Is there a free UML diagram tool?Copied!Link to this section

Yes. Whimsical's free plan includes boards, the sequence diagram tool and all the UML templates linked in this article.

Ready to try it? Open a free Whimsical board and start from a UML template (class, sequence, use case, activity or state), or describe your system and let Whimsical AI draft the diagram.

Learn