Layout grammars

A layout grammar is a rule for turning content with a known shape into geometry. It is not a graph-drawing algorithm: nothing here minimizes edge crossings or relaxes a force model. Each grammar assumes the content already has a structure (an ordered set of bands, a set of parallel sequences) and places boxes accordingly, by arithmetic alone. The result is deterministic and inspectable: the same content and sizing give the same diagram every time.

The engine works with eleven grammars. A notation binding that names anything else is refused when it loads. They split by who places the geometry:

Nine of the eleven are composed by the engine. The two others are different in kind:

• Graph is produced by EA's own layout and tidied afterward.
• EA-semantic cannot be produced by placing boxes, and is recorded so that the AI can say so.

Three questions, never one yes-or-no. Whether a grammar "is available" is three separate questions, and they only coincide for the composed grammars:

• Implemented: the engine has a composer for it. Derived from the engine on every call, never from a written-down list.
• Producible: a diagram of this type can be produced, by a composer or by EA's layout. Graph is producible and has no composer; EA-semantic is neither.
• Composed: the coordinates are ours to compute. True for the nine engine-placed grammars.

What the status words mean for you. A diagram type the engine cannot compose is not a wall: where a binding is missing, the engine composes from its defaults and the gap is fidelity (measured sizes, spacing, prefix), not capability. Where the content wants an arrangement none of these grammars gives, the AI tells you and either approximates from a composed grammar (saying what was approximated) or hand-places the geometry (saying so).

Layered bands

Logic: Deterministic. Composer: compose_layered_bands. Horizontal bands stacked top to bottom, each holding items laid out left to right.

What it suits. Content where the vertical axis carries meaning (a layering, a tiering, an order of abstraction) and the horizontal axis carries only membership: reference models, capability maps with one band per level, technology stacks, maturity tiers. The test: can you name what moving an item from one band to another would mean? If not, the content is a flat set and this is the wrong grammar.

Reads well when:

• the layer order matches the audience's mental order and is used consistently
• item size is uniform within a band (different bands may differ)
• every band has one width, the widest band's, so the stack has a straight right edge (a narrower sparse band reads as a drawing error; this is the opposite of the nested grid's rule, on purpose)
• band heights follow their contents, wrapping to a second row at the same size rather than shrinking boxes
• each band has a visible label strip, and an empty band keeps its label row so the emptiness is deliberate

Reads badly when: there are too many bands (past about seven it is a list); one band is enormous (a mislabeled grid); bands are empty with no explanation; someone reads meaning into how full a band is (bands share a width); or two dimensions are used at once without saying so.

Limits worth knowing. Bands step down by band height plus a gap. A row wraps at a default of 900 units. An explicit minimum band width narrower than the contents is a conflict, reported and answered by you ("widen" or "overlap"); widening is applied when nobody answers.

Lanes

Logic: Deterministic. Composer: compose_lanes. Parallel tracks, each carrying a sequence of items that flows along the track (swimlanes).

What it suits. Content with two axes where one is sequence and the other is responsibility: process flows, value streams, handoff-heavy workflows, migration sequences with one lane per workstream. Both must be true: step order and who performs each step.

Reads well when:

• items at the same sequence position line up on the flow axis (the engine allocates one slot per position, sized to the longest item at that position, and centers each item in it, so a handoff reads as a step across)
• there are three to six lanes
• lane thickness follows the largest item in the lane
• lanes abut, with a label area inside the lane band
• horizontal lanes are used for long sequences with short lane names, vertical lanes for many lanes or long lane names

Reads badly when: a lane is nearly empty; ragged lane lengths pretend to be alignment; a sequence position means different things in different lanes; lanes stand in for layering; or correct lanes have no connectors drawn.

Limits worth knowing. Lanes run horizontally (stacked downward, items flowing left to right) or vertically. Each item reports the slot it occupies. A lane may override item width and height only.

Nested grid

Logic: Deterministic. Composer: compose_nested_grid. Containers within containers, each laid out as a grid of its children.

What it suits. Containment is the whole structure and there is no sequence: domain and subdomain maps, capability maps where the levels are true decomposition, portfolio views grouped by owner, information models by subject area, organization structures. The test: would an arrow between two of these boxes add anything? If yes, the content is a graph.

Reads well when:

• nesting is two or three levels deep
• containers are sized by their contents (a container is not stretched to its cell, so a group of twenty is visibly bigger than a group of two; the opposite of the layered-bands rule, on purpose)
• grids are close to square
• cells are uniform within a level, as stated by the parent
• a title strip sits above the padding so a name never sits on its children
• there is real whitespace between cells

Reads badly when: it nests four or more levels; containers are sized alike; the grouping is arbitrary (a grid of "Other"); a container is empty with no explanation; or connectors are added to clarify the nesting.

Limits worth knowing. The default depth limit is three. A deeper tree is refused, naming the path; the limit can be raised deliberately. Input is a recursive tree: a node with items is a container and needs a name, a node without is a leaf and needs an id. Nesting in EA is not only geometric: a box drawn inside another is not the same as an element owned by that container, so get the model relationship right first.

Radial

Logic: Deterministic. Composer: compose_radial. A hub and its spokes: items on a ring around a center, optionally with a second ring hanging off each one.

What it suits. One center with peers around it whose order does not matter: capability wheels, service catalogs around an organization, a stakeholder map, a cycle of four or five stages, a phase wheel. The test: is there genuinely a center?

Reads well when:

• spokes are equal: the radius is the clear gap between the hub's border and each item's border, so the drawn spoke is the same length all the way round whatever shape the boxes are
• there are few enough items to see the circle (past a dozen it is a crowd)
• there are one or two rings
• the hub earns the central position

Reads badly when: there is no real center; a ring implies an order; labels are long (wide boxes force the ring to grow); or arcs are expected.

Limits worth knowing.

• The radius is a floor. If items would collide it is widened, and the radius used comes back on the result. The widening is bounded (default maximum 900); beyond it the composition is refused with the count, the box size, the arc and the radius that would be needed, and four ways out (fewer items, wider sweep, smaller items, higher maximum).
• The default ring depth is two; a third ring is refused.
• A full circle by default, with a start angle measured clockwise from twelve o'clock; a partial sweep spreads items inclusive of both ends.
• Sizing comes from the spec for every ring; a size on a node or the hub is refused, not ignored. For per-ring sizing use the radial tree.
• Borders are modeled as rectangles. An element EA draws as a circle bulges at the diagonals, and the result reports by how much.
• There is no arc in EA's connector vocabulary: straight or Bezier lines only.

Two-column cycle

Logic: Deterministic. Composer: compose_two_column_cycle. A cycle drawn as two columns: the flow runs down one and back up the other, closing the loop across the top.

What it suits. A closed sequence of a handful of steps or states where each step carries its own content (entry, do and exit behavior, a short code, a description) and the reader must see that the sequence returns to its start: a state machine drawn as a cycle, an order lifecycle, an approval loop, a shift rotation.

Reads well when:

• the boxes have content
• there are four to eight items (twelve is the practical ceiling)
• items are passed in reading order, with connectors added by the caller
• the composer guarantees one shared width (a straight outline), one row pitch for the whole composition, and aligned centers rather than aligned tops (so the fold and the closing step are horizontal)

Reads badly when: the sequence does not close; uniform empty boxes (use radial); one box is much taller than the rest (the pitch is set by the tallest); there are too many items; or the two columns are read as two groups.

Limits worth knowing. Boxes may differ in height. The row pitch is a floor, widened to clear the tallest box, and the pitch used is returned. A column pitch narrower than the item width is refused. With an odd count the empty cell is the top of the return column, so the closing step is the diagonal one. There are no containers. Do not hand the whole cycle to the uniform-sizing check as one role (heights differ); declare a role per height.

Matrix

Logic: Deterministic. Composer: compose_matrix. A regular grid of cells addressed by row and column, with row headers down the side and column headers across the top.

What it suits. Framework grids a reader counts along: the Zachman framework (rows by interrogatives), capability by channel, any two-axis table where the address is the information. The shipped Zachman interface binding uses it.

Reads well when:

• cells are uniform: one cell width and height taken from the fullest cell, one column pitch and one row pitch, whether a cell holds nothing, one element or nine
• headers are full-extent strips on the lattice
• empty cells keep their full slot and are returned marked empty

Reads badly when: one crowded cell makes every cell that big (reported as the most items in one cell); the matrix is sparse and mostly empty boxes; or it is used where size should carry information (use nested grid).

Limits worth knowing. Gaps must be positive: touching cells cannot be told apart. Cells address rows and columns by key (the header's id, else its name), never by position. Items inside a cell form a sub-grid. The corner is always reserved and drawn only when given. A composed matrix draws every cell at one size, while a Sparx-authored reference may use per-column widths, so do not expect byte-for-byte reproduction. EA's own matrix overlay draws the header chrome in that reference, so a composed matrix's headers differ.

Radial tree

Logic: Deterministic. Composer: compose_radial_tree. A mind map: a central topic, main branches around it, and sub-branches hanging off those to several levels.

What it suits. Mind maps, with the weighted allocation of angular room that the plain radial grammar lacks: a branch with eight children needs more room than a branch with one. The shipped mind-mapping binding uses it.

Reads well when: angular room is allocated by weight, not count (a branch's wedge is proportional to the number of leaves in its subtree); branches cannot interleave (each node owns an interval of bearings); spokes from each parent are equal in drawn length; and per-ring sizing is stated by the parent.

Reads badly when: the same things that hurt a radial, plus a tree so uneven for the sweep that it cannot be laid out without collision, or arc connectors are expected.

Limits worth knowing. The default depth limit is four (deeper is refused) and the default maximum branch sweep 120 degrees. A node may restate item size and radius for its own children; it does not cascade. A partial sweep is not inclusive of both ends (branches sit at wedge centers). The layout is built, tested for collisions, and every clear gap widened by a fixed step (up to 20 rounds) until clean; the result reports how much widening was needed (1.0 is the usual case). Levels are not concentric circles: equal clear gaps beat level-uniform radii because the checker's spoke rule measures drawn spokes.

Chevron stack

Logic: Deterministic. Composer: compose_chevron_stack. A value chain drawn as interlocking arrow-shaped stages, with an optional band of supporting strips spanning the row.

What it suits. Value chains and process chains where each stage points to the next. The shipped value-chain diagram type uses it.

Reads well when: stages abut exactly (the interlock is drawn by the element's own renderer outside the stored rectangle, so the stage pitch equals the stage width exactly and the notch depth cancels out); every stage is the same width; and supporting strips span the whole row and abut each other and the stage row.

Reads badly when: arrows are drawn between stages that already point at each other, or the pitch is widened (it opens a sliver of background and nothing downstream can detect it, so it is not a setting).

Limits worth knowing. No per-item overrides at all. The notch depth defaults to 20% of the width, at most 50%. Supporting strips go above or below; their height defaults to half the stage height. The result reports the stored rectangles and where the last point lands. The AI declares the output to the checker as stacks, never rows: the stages abut deliberately and the row rule would report them. A chain of one composes.

Treemap

Logic: Deterministic. Composer: compose_treemap. A rectangle tiled so that each tile's area is proportional to a weight, grouped under titled strips.

What it suits. Quantity carried by area: portfolio cost or size by group and item. No shipped binding uses it.

Reads well when: the tiling is squarified (tiles as close to square as the weights allow, so areas are comparable by eye); the region is an input (its width and height are stated and the weights divide exactly that); tiles abut (there is no gap setting, because whitespace would tax small tiles more than large ones); and rounding is closed on boundaries rather than sizes, so tiles partition the region exactly with no gap or overlap.

Reads badly when: weights do not vary enough to see; one dominant weight (small tiles bottom out at the floor and the result reports the area error); or there are too many tiles.

Limits worth knowing. Two levels only (groups and tiles). A group's weight is the sum of its tiles'. The minimum tile side is 48 units on both axes. A zero weight is legal and drawn at the floor; a negative weight is refused. At most 200 boxes per region. A group that cannot hold its tiles at the floor is refused, with the capacity, the demand and three remedies. No color (a binding or caller decides, and the color rule requires a legend) and no connectors. The result reports honestly how many tiles sit at the minimum, the area errors and the worst aspect ratio. Header strips are taken out of each group's allocation, so tile areas are faithful within a group and only approximately so across groups.

Graph

Logic: Rule-based. EA's layout places the elements; the composition engine measures, tidies and checks the result.

A graph or a tree where nothing about the content says where a box must sit. EA's own layout places the elements, and the engine tidies afterward.

What it suits. Content whose relationships are the structure: dependency and interaction networks, class, component, deployment, package, object and use-case models, trees and taxonomies, decision structures, flows with no owners. Most diagram types in most notations are graphs, and this is their honest home, not a consolation prize. Two tests, both should pass: would a general-purpose layout give a reviewer something acceptable, and is there no structure (strata, owners, containment, a center) that a composed grammar would show?

What the engine still contributes. Everything except coordinates: measured element sizes, spacing (the layout call reads it as layer and column spacing), default and trunk routing, the title convention, and which visual channels are claimed and free.

Reads well when: sizes are uniform by role; spacing is stated rather than left at the layout default; one routing style is used throughout; a title is drawn or supplied by the frame, never both; and geometry checks run after the layout call (overlap, positive size, fits-the-canvas), because EA placed the boxes and nothing is guaranteed.

Reads badly when: it is used for content with strata, owners, containment or a center; position is read as meaning; boxes are hand-nudged after layout; or the graph is too dense for any layout (split or filter it).

Limits worth knowing. layout_diagram styles are Orthogonal, Hierarchical, Circular and Sequence; a direction can be given but has no effect. It refuses to stand in for a composed grammar to improve a coverage figure, and it refuses diagram types whose arrangement the type dictates.

EA-semantic

Logic: Not available. Composer: none, by design. The diagram type itself dictates the arrangement, and coordinates are the wrong output. Placing boxes on one is fighting the editor, which derives the arrangement from the content. It is recorded so that the AI can tell you the diagram type is classified as not producible.

What it suits. Diagram types whose quality is order, not geometry: message exchanges (lifeline order across the page, message order down it; a lifeline's height is set by the messages it carries) and timing diagrams (a waveform per participant against a shared time axis).

Measure before you classify. A type that sounds sequential is not EA-semantic unless EA does the placing. A state machine's states and a collaboration's participants sit where a modeler put them, in many sizes, with spacing like a class diagram's, and are graph.

It refuses: being composed (it has no composer, by design); being laid out as a graph to make a diagram appear (a message exchange as a free graph has its elements and is no longer a message exchange); and being judged by geometry (passing the overlap and sizing checks proves nothing about message order). The AI says the type is recorded but not producible, and stops.

Reviewing any composed diagram

For the composed grammars the first three checks are guaranteed arithmetically; for a graph they are checks to run after the layout call.

1. No two items overlap and no two containers overlap (items against items, containers against containers, never mixed).
2. Every rectangle has positive width and height and obeys the sign convention.
3. The composition fits the canvas: compare the returned bounding box with the space available before placing.
4. Uniform sizing within a role, with the stated exceptions (two-column cycle heights; nested-grid containers sized by contents).
5. The axes mean something and the diagram says what.
6. A reader who was not in the room can name the structure.