119 lines
6.6 KiB
Markdown
119 lines
6.6 KiB
Markdown
# 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
|