1. Diagram type — Use the decision matrix below
2. Key elements — Entities, steps, concepts, actors
3. Relationships — Flow direction, connections, hierarchy
4. Complexity — Number of elements (target: under 20 for clarity)

• Nodes/entities — What are the boxes/shapes?
• Connections — What connects to what, and with what label?
• Hierarchy — What contains what, what comes before what?
• Decision points — Where does the flow branch?

references/element-types.md

references/excalidraw-schema.md

1. Text inside shapes — Use

   boundElements

   on the shape and a separate text element with

   containerId

   . Never use a

   label

   shorthand:
   json

   [
     {
       "id": "step-1",
       "type": "rectangle",
       "x": 100, "y": 100, "width": 200, "height": 80,
       "boundElements": [{ "type": "text", "id": "text-step-1" }]
     },
     {
       "id": "text-step-1",
       "type": "text",
       "x": 130, "y": 128, "width": 140, "height": 24,
       "text": "My Step", "originalText": "My Step",
       "fontSize": 20, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "step-1", "lineHeight": 1.25, "roundness": null
     }
   ]

2. Arrow labels — Also use

   boundElements

   + separate text element with

   containerId

   . Never use a

   label

   shorthand on arrows:
   json

   [
     {
       "id": "arrow-1",
       "type": "arrow",
       "x": 100, "y": 150,
       "points": [[0, 0], [200, 0]],
       "boundElements": [{ "type": "text", "id": "text-arrow-1" }]
     },
     {
       "id": "text-arrow-1",
       "type": "text",
       "x": 160, "y": 132, "width": 80, "height": 18,
       "text": "sends data", "originalText": "sends data",
       "fontSize": 14, "fontFamily": 5,
       "textAlign": "center", "verticalAlign": "middle",
       "containerId": "arrow-1", "lineHeight": 1.25, "roundness": null
     }
   ]

3. Arrow bindings — Use

   startBinding

   /

   endBinding

   (not

   start

   /

   end

   ). Connected shapes must list the arrow in their

   boundElements

   :
   json

   {
     "id": "shape-1",
     "boundElements": [
       { "type": "text", "id": "text-shape-1" },
       { "type": "arrow", "id": "arrow-1" }
     ]
   }

   json

   {
     "id": "arrow-1",
     "type": "arrow",
     "startBinding": { "elementId": "shape-1", "focus": 0, "gap": 1 },
     "endBinding": { "elementId": "shape-2", "focus": 0, "gap": 1 }
   }

4. Element order for z-index — Always declare shapes first, arrows second, text elements last. This guarantees text renders on top and is never obscured by arrows or other shapes.
5. Positioning — Use grid-aligned coordinates (multiples of 20px when

   gridSize: 20

   ). Leave 200-300px horizontal gap, 100-150px vertical gap between elements.
6. Unique IDs — Every element must have a unique

   id

   . Use descriptive IDs like

   "step-1"

   ,

   "decision-valid"

   ,

   "arrow-1-to-2"

   ,

   "text-step-1"

   .
7. Colors — Use a consistent palette:

   Role	Color	Hex
   Primary entities	Light blue	#a5d8ff
   Process steps	Light green	#b2f2bb
   Important/Central	Yellow	#ffd43b
   Warnings/Errors	Light red	#ffc9c9
   Secondary	Cyan	#96f2d7
   Default stroke	Dark	#1e1e1e

1. Save as

   <descriptive-name>.excalidraw

2. Provide a summary:

   Created: user-workflow.excalidraw
   Type: Flowchart
   Elements: 7 shapes, 6 arrows, 1 title
   Total: 14 elements
   
   To view:
   1. Visit https://excalidraw.com → Open → drag and drop the file
   2. Or use the Excalidraw VS Code extension
   3. Or open in Obsidian with the Excalidraw plugin

references/icon-libraries.md

• User requests an AWS/cloud architecture diagram
• User mentions wanting specific service icons
• You need to check if icon libraries are available

"Your request includes 15 components. For clarity, I recommend: (1) High-level architecture diagram with 6 main components, (2) Detailed sub-diagrams for each subsystem. Want me to start with the high-level view?"

• Flow direction: Left-to-right for processes, top-to-bottom for hierarchies
• Spacing: 200-300px horizontal, 100-150px vertical between elements
• Grid alignment: Position on multiples of 20px for clean alignment
• Margins: Minimum 50px from canvas edge
• Text sizing: 28-36px titles, 18-22px labels, 14-16px annotations
• Font: Use

  fontFamily: 5

  (Excalifont) for hand-drawn consistency. Fallback to

  1

  (Virgil) if 5 is not supported.
• Background zones: For architecture diagrams, add semi-transparent dashed zone rectangles (

  opacity: 35

  ,

  strokeStyle: "dashed"

  ,

  roughness: 0

  ) as the first elements in the array to create visual grouping regions. See

  references/excalidraw-schema.md

  → Background Zones.
• Element order: zones first → shapes → arrows → text elements (ensures correct z-index and text always renders on top)

• ❌ Using

  label: { text: "..." }

  shorthand on shapes or arrows — not supported by the Excalidraw parser
• ❌ Putting

  text

  directly on shape elements without

  containerId

• ❌ Using

  start

  /

  end

  for arrow bindings — use

  startBinding

  /

  endBinding

  with

  elementId

  /

  focus

  /

  gap

• ❌ Forgetting to add arrows to their connected shapes'

  boundElements

  arrays
• ❌ Omitting

  originalText

  ,

  lineHeight

  ,

  autoResize

  , or

  backgroundColor: "transparent"

  from text elements inside containers
• ❌ Omitting required base properties (

  angle

  ,

  strokeStyle

  ,

  opacity

  ,

  groupIds

  ,

  frameId

  ,

  index

  ,

  isDeleted

  ,

  seed

  ,

  version

  ,

  versionNonce

  ,

  updated

  ,

  link

  ,

  locked

  ) — elements will not render
• ❌ Missing

  "files": {}

  at the top level of the JSON
• ❌ Using

  roundness: { "type": 3 }

  on ellipses — ellipses must use

  roundness: null

• ❌ Missing

  lastCommittedPoint

  ,

  startArrowhead

  ,

  endArrowhead

  on arrows
• ❌ Declaring text elements before arrows — text renders underneath and gets obscured
• ❌ Floating arrows without bindings (won't move with shapes)
• ❌ Overlapping elements (increase spacing)
• ❌ Inconsistent color usage (define palette upfront)
• ❌ Too many elements on one diagram (break into sub-diagrams)

• All elements have unique IDs
• Every element has ALL required base properties:

  angle

  ,

  strokeStyle

  ,

  opacity

  ,

  groupIds

  ,

  frameId

  ,

  index

  ,

  isDeleted

  ,

  link

  ,

  locked

  ,

  seed

  ,

  version

  ,

  versionNonce

  ,

  updated

• index

  values are assigned in order (

  "a0"

  ,

  "a1"

  , …) with text elements getting higher values than shapes/arrows
• Top-level JSON includes

  "files": {}

• Shapes with text use

  boundElements

  + separate text element with

  containerId

• Text elements inside containers have

  containerId

  ,

  originalText

  ,

  lineHeight: 1.25

  ,

  autoResize: true

  ,

  roundness: null

  ,

  backgroundColor: "transparent"

• Arrows use

  startBinding

  /

  endBinding

  (with

  elementId

  ,

  focus

  ,

  gap

  ) when connecting shapes, plus

  lastCommittedPoint: null

  ,

  startArrowhead: null

  ,

  endArrowhead: "arrow"

• Connected shapes list the arrow in their

  boundElements

  arrays
• Element order: shapes → arrows → text elements (text always on top)
• Ellipses use

  roundness: null

  (not

  { "type": 3 }

  )
• Coordinates prevent overlapping (check spacing)
• Text is readable (font size 16+)
• Colors follow consistent scheme
• File is valid JSON
• Element count is reasonable (<20 for clarity)

• Complex curves are simplified to straight/basic curved lines
• Hand-drawn roughness is set to default (1)
• No embedded images in auto-generation (use icon libraries for service icons)
• Maximum recommended: 20 elements per diagram for clarity
• No automatic collision detection — use spacing guidelines