sap-architecture/references/do-and-dont.md

Do and Don't — consolidated SAP rules

Every entry below is a verbatim quote from the official SAP BTP Solution Diagram Guidelines, with the source file in the footer of each item.

Areas / containers

DO — alternate fill / no-fill when nesting:

"When nesting different areas inside each other, you should alternate between using a fill and not using a fill to provide sufficient contrast between the areas. The parent layer is usually the BTP layer." — diagr_comp/areas.md

DON'T — change the style of stacked layers:

"Areas can be shown as stacked to display multiple grouped layers or items. The style should not be changed in order to keep diagrams consistent." — diagr_comp/areas.md

DO — use the fixed corner radius:

"A fixed corner radius of 16 pixels is recommended." — diagr_comp/areas.md

Color usage

DO — use one consistent palette family (Horizon):

"Horizon is the default visual style for SAP Products … This also applies to diagrams." — foundation.md

DON'T — paint everything in accent colors:

"Secondary colors can be applied to accentuate important elements. They make a vivid contribution to the overall UI and should be used sparingly." — foundation.md

DON'T — overpower with primary/non-SAP either:

"It is not recommended to use the colors too heavily, they can overpower the diagram." — diagr_comp/areas.md

Connectors / arrows

DO — use the fixed semantic mapping:

"Trust Flows are usually pink / Authentication flows are usually green / Authorization flows are usually indigo / Firewalls and Network barriers are thick grey lines" — lines_connectors.md

DO — pick the line style that matches the data-flow semantics:

"Solid lines for direct, synchronous request-response data flows / Dashed lines for indirect, asynchronous data flows / Dotted lines for optional data flows / Thick lines for firewalls only" — foundation.md

DON'T — invent your own arrow style:

"Avoid creating your own arrows; use the ones available in the library instead as they adhere to the correct styling guidelines." — solution_diagr_intro/big_picture.md

DON'T — use thick lines for anything other than firewalls:

"Thick lines for firewalls only" — foundation.md

Icons

DO — use the grey-circle service icons:

"For diagram visualization it is mandatory to use the version with grey background circle." — diagr_comp/icons.md

DO — use generic icons for non-SAP elements (devices, databases):

"This set of icons with soft gradients is used for all elements that are either generic such as devices or databases. … The primary color used is neutral grey." — diagr_comp/icons.md

Product names

DO — pair SAP product names with the SAP logo:

"SAP product names must be paired with the SAP logo." — diagr_comp/product_names.md

DON'T — over-do the SAP logo:

"It is not recommended to use too many SAP logos in the same diagram. Use text only elements instead." — diagr_comp/product_names.md

The skill applies this rule by placing exactly one SAP logo per diagram (top-right of the BTP zone). Service cards inside the BTP zone don't get individual logos — the one zone-level logo carries them.

Text / typography

DO — keep text sizes consistent when scaling:

"When scaling elements up or down, take care to ensure text sizes remain consistent." — solution_diagr_intro/big_picture.md

DO — use the four-style hierarchy:

"To create hierarchies four text styles were derived from Fiori Horizon." — diagr_comp/text.md

Spacing

DO — use the SAP-logo-height rule:

"Spacing around objects should be even and roughly the height of the SAP Logo." — foundation.md

Legend

DO — include a legend in L1 / L2:

"Including a legend in each diagram is crucial to clarify these meanings." — foundation.md

DON'T (L0 only) — force a legend onto a marketing-level diagram:

"In such diagrams, connectors maintain neutrality and the content is streamlined to essentials, eliminating the necessity for a legend, but a short description is recommended." — solution_diagr_intro/big_picture.md

PowerPoint vs draw.io

DO — switch to draw.io if PowerPoint constrains the layout:

"Slide dimensions are unalterable, so if you find the available space inadequate for your diagram, avoid downscaling all the elements to accommodate it. … If your diagram is too large for PowerPoint, consider switching to draw.io." — solution_diagr_intro/big_picture.md

This skill always emits draw.io.

What this skill enforces automatically

validate.py catches:

• Off-palette hex (warns)
• Dark / branded page background (pageBackgroundColor not in {white, transparent}) — error
• Off-vocabulary pill verbs — pills labelled PROMPT, ROUTE, CONTEXT, DELEGATE, INVOKE, FETCH, EXECUTE, etc. trigger warnings. Use canonical SAP verbs: TRUST, Authenticate, Authorization, A2A, MCP, ORD, HTTPS, OData/REST, REST/Token, SAML2/OIDC, OIDC, SCIM, Identity Lifecycle, Group, Role, Role Collection, Source, Target, Destination.
• Multi-logo over-use — more than 6 SAP logos in one diagram triggers a warning per product_names.md.
• absoluteArcSize=1 missing when arcSize is set (warns; autofix repairs)
• strokeWidth outside {1, 1.5, 2, 3, 4} (warns)
• strokeWidth>=3 flagged for review (firewall-only rule)
• Edge label without labelBackgroundColor=default (warns)
• Bent orthogonalEdgeStyle edge (centers not aligned on any axis) — error
• Label text wider than its shape — error
• Sibling shape overlap (not contained, not transparent, not pill) — error
• Off-grid coordinates — warns; autofix repairs
• fontFamily ≠ Helvetica — warns; autofix repairs
• Duplicate ids, missing mxGeometry, XML comments — error

compare.py additionally penalises:

• Wrong page background (white SAP canvas vs candidate dark theme)
• Wrong zone hierarchy — e.g. nesting Joule inside the BTP zone when the SAP reference puts them side by side
• Wrong edge stroke palette — semantic mismatches (green where magenta is expected) that the global palette set hides
• Pills using novelty verbs instead of the canonical SAP vocabulary

What validate.py does not check (yet — manual review):

• "Use the grey-circle icon variant" — visual check, not extractable from XML
• "Don't use accent colors heavily" — proportional rule, hard to quantify
• "Spacing roughly = SAP logo height" — context-dependent
• "Legend present" — checked only via warning if level=L1|L2 and no legend element exists