For Library Authors

How to add new shapes, update styles, and manage the shape library.

Table of contents

1. Adding a new shape
   1. Option A: Extract from draw.io (recommended)
   2. Option B: Write YAML manually
2. Re-running extract on an updated reference file
3. Updating visual styles
4. Adding properties to shapes
5. Deprecating a shape
6. Releasing

---

Adding a new shape

Option A: Extract from draw.io (recommended)

The fastest way. No hand-writing YAML or XML.

1. Open draw.io and drag the ArchiMate shapes you want onto a blank canvas
2. Style them (colors, font, size)
3. Add custom properties via Edit > Edit Data (owner, status, etc.)
4. Save as reference.drawio
5. Run extract:

npx architecture-blocks extract reference.drawio --output shapes/
#   extracted application-component → application/application-component.yaml
#   extracted business-actor → business/business-actor.yaml
# 2 shapes extracted, 0 skipped.

Bulk extraction: drop as many shapes as you want on one canvas. The extract command processes all of them in one run.

Option B: Write YAML manually

Create shapes/<layer>/<block-id>.yaml:

blockId: my-new-shape
name: My New Shape
layer: application
archimate:
  stencil: mxgraph.archimate3.application
  typeAttr: appType
  typeValue: comp
visual:
  fillColor: "#99ffff"
  strokeColor: "#00cccc"
  fontColor: "#000000"
  fontSize: 12
  fontStyle: 0
dimensions:
  width: 120
  height: 60
properties:
  - key: owner
    label: Owner
    type: string
    default: ""

Validate: npm run validate

Re-running extract on an updated reference file

Action	What happens
Add new shapes to canvas, re-run extract	New shapes extracted, existing ones skipped
Update styles on canvas, re-run extract	Skipped by default. Use --force to overwrite
Remove shapes from canvas, re-run extract	YAML files stay (not auto-deleted). Remove manually

# First time
npx architecture-blocks extract reference.drawio

# Later: added 3 new shapes
npx architecture-blocks extract reference.drawio
#   skip application-component (exists, use --force to overwrite)
#   extracted new-shape-1 → ...
# 3 shapes extracted, 5 skipped.

# Force overwrite all (after updating styles)
npx architecture-blocks extract reference.drawio --force

Updating visual styles

1. Edit the YAML file directly — e.g., change fillColor
2. Or update in draw.io and re-extract with --force
3. Rebuild:

npm run validate   # Check YAML is valid
npm run build      # Regenerate libraries/*.xml
npm test           # Verify round-trip integrity (415 tests)

Adding properties to shapes

Properties give shapes context. See Shape Properties for the full guide.

properties:
  - key: owner
    label: Owner
    type: string
    default: ""
  - key: status
    label: Status
    type: enum
    default: active
    options: [active, deprecated, planned, retiring]

Deprecating a shape

Don’t delete — deprecate first:

blockId: old-shape
deprecated: true
deprecatedSince: "0.3.0"
replacedBy: new-shape

Shape stays functional for 2 minor versions, then removed in next major. See Breaking Changes.

Releasing

1. Commit changes → PR → CODEOWNERS review → merge
2. Create a GitHub Release with semver tag (e.g., v0.2.0)
3. GitHub Actions auto-publishes to npm and GitHub Packages

See Versioning for semver rules.