Compose a diagram

Goal

Build a diagram from model content, rather than hand-placing it, by choosing a layout grammar, computing the geometry, placing and styling the elements, then verifying, linting and correcting. For an architect. You end with a diagram that reads as deliberate, a verified render, a lint report with its limits stated, and a note saying what it shows.

Where it runs

This scenario needs the MCP server and local code execution. Computer use covers its UI steps.

Before you start

• The start-of-session check done.
• The elements and connectors already in the model. This scenario places them. It does not create them (Build a model from source documents).
• A chosen diagram type. If you do not have one, run Choose the right diagram first.
• A target package for the diagram, and a baseline of it if it holds content.
• Local code execution, because the composition engine runs on the machine where EA runs (Composition engine). Its modules are pure arithmetic and make no requests to the repository. Without local code execution this scenario is not available.

A diagram works when a reader can follow its argument without being told how. ea-diagram-composition is language-neutral: nothing in it knows what ArchiMate or BPMN is. It reads each notation's conventions from a binding, a data file that holds a technology's diagram types, sizing, spacing, title convention, routing and standard views. The loop is the heart of the skill: choose a grammar, compute geometry, place and style, verify, lint, correct.

Never hand a diagram over without looking at it. The loop is bounded: three correction passes, then report what is left. If it is still wrong after three, the grammar was the wrong choice, not the spacing. The AI says so rather than iterating forever.

Steps

1. AI with computer use; otherwise you If EA is not running or the model is not open, start EA and open it. Engine ea-diagram-composition resolves the language binding (rule-based). Pass both the diagram's style and its diagram type: about half of real diagrams carry no technology type in their style and identify themselves by diagram type alone. You Decide when the answer is ambiguous or unbound.
2. Engine ea-diagram-composition asks whether the diagram can be produced, and who places it: the engine, EA, or the diagram type itself. You Decide when it cannot be produced.
3. AI ea-diagram-composition chooses a grammar. You Decide when none fits cleanly.
4. Engine ea-diagram-composition computes the geometry with the composer for that grammar. The composers take plain content and return a rectangle for each item, and each container carries its own rectangle and a label rectangle. Item ids are preserved, so EA element ids pass through as they are. The spacing and sizing come from the binding, which measured them from real diagrams. The AI also passes the item names, so the box width is widened to the longest space-free run before the engine sees it. You Answer the question when the width and the content conflict.
5. AI Power Tools ea-diagram-composition creates the diagram and places the elements at the computed rectangles, with no automatic layout. A named layout style discards every coordinate just computed.
6. AI Power Tools ea-diagram-composition styles the elements and then the connectors. Add connectors to the link layer first, since a connector needs a stored link before it can be styled. Choose the scope deliberately: styling a diagram's placement affects one placement on one diagram, and styling the element itself changes it on every diagram. Reach for the first. Each notation also claims some visual channels: ArchiMate's layer colors are spoken for, so recoloring them by lifecycle destroys the notation while looking like a feature. Use border, opacity or an icon instead.
7. AI Power Tools ea-diagram-composition verifies (verify_diagram, with the picture's SVG). The result gives the image with the placed rectangles, z-order, link routing, color and width, and the canvas extents. To learn what color EA actually drew, read the SVG. A color property read back tells you nothing: EA echoes whatever was written, and some shapes refuse a fill outright.
8. Engine ea-diagram-composition lints (rule-based). See the table below.
9. AI Power Tools ea-diagram-composition corrects and re-verifies, at most three passes (set_diagram_object, resize_diagram_objects, neaten_diagram_objects, then steps 7 and 8).
10. You Look at the render, and judge what the linter cannot: each notation already claims some visual channels, one variable per channel, uniform sizing within a role (varying size reads as varying importance), empty space is structure, and fewer connectors is usually better than more. Ask what the diagram is for, leave out what does not serve it, and have the AI say what it left out.
11. AI Power Tools ea-modeling writes the diagram's note last, as one sentence saying what it shows (update_diagram). A diagram is created with an empty note.

Resolving the binding.

An unbound or ambiguous answer is a finding to report. The AI quotes the reason and says what it did instead: compose with the engine's defaults for unbound, or choose a candidate explicitly. Never take the first candidate. Composing against another notation's binding is worse than composing against none.

Producibility. Four properties, read in this order: can the diagram be produced at all, does the engine compute its coordinates or does EA place it, does a composer exist, and who places it. Not producible means the diagram type dictates its own arrangement, so coordinates are the wrong output: the AI says so and stops. It does not compose the nearest shape it does have. Producible and composed goes on to step 4. Producible and not composed, the graph grammar, skips step 4: create the elements, run EA's layout with the spacing the binding gives, then style and verify.

Grammars. There are eleven. Nine have a composer, graph uses EA's own layout and tidies afterward, and EA-semantic is not producible.

If none fits, say so and use the graph grammar. A capability model in swimlanes is not a swimlane diagram. It is a capability model that has been made harder to read.

When the width and the content conflict, the AI asks you. A width stated on purpose and content wider than it are both facts, and there are two legitimate drawings: extend the box, or keep the width and let the text overlap the border. Which one a diagram wants is not the AI's call. The composer reports the conflict with the question ready to put. Compose with your answer. Widening is what happens when nobody answers, because it makes the stored geometry equal what EA paints. A conflict that has not been answered is a question the AI still owes you.

What the lint checks.

The groupings are the AI's job, not the linter's. Which elements play one role, sit in one row or column, form a stack or ring a hub are composition facts that geometry cannot tell. A rule with no grouping does not run, and the report lists which rules did not run. A clean report means no errors, not "nothing found", and it means no defect this linter knows how to measure. It does not mean the diagram reads well.

Prompts to use

Opening

Follow-ups

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks.

Checking the result

• Accurate. The verify step shows each element at the computed rectangle. The SVG's fill and stroke match the colors intended. Every connector that should be styled has a stored link, and its route and color are as set.
• Complete. Every element that belongs on the diagram is on it, and nothing else is. The lint report lists any rule that did not run and why. The report says what was deliberately left out. The note is set.
• Nothing unintended changed. Model-wide appearance is unchanged unless you chose it. Comparing the model with its baseline shows only the new diagram and its placements.

Variations

• A graph or tree. Use the graph grammar: create the elements, run EA's layout with the binding's spacing, then style, verify and tidy (Tidy and style a diagram).
• A hub and peers. The radial grammar, with the sweep stated to the angle rule.
• An executive view. Compose, then hide connector labels and stereotypes and collapse parallel connectors. See Tidy and style a diagram.
• Straight from a recommendation. Take the recommendation from Choose the right diagram, including how it is to be generated.

Limitations

• An EA-semantic diagram type is not producible. Its arrangement is the content, so coordinates are the wrong output.
• A clean lint report is not a claim the diagram looks right. The linter cannot know what two elements have in common, and cannot judge purpose.
• EA grows boxes. A name with no space is not wrapped. Stored geometry and drawn geometry then differ.
• Connectors EA draws but does not store cannot be styled. Add the link first.
• Bindings are conventions measured from sample models, and a customer's own technology has none. Compose with the engine's defaults and say so.
• Stored geometry is not always where EA draws it. See Start from a model pattern. Judge by the render.