Icons (ext:icons)

Version: 1.0 Status: Stable Identifier: icons

Overview

The icons extension adds visual icon support to TDL nodes. Icons enhance diagram readability by providing recognizable visual markers for technologies, services, and concepts.

Declaration

#!ext icons
@arch My Architecture

Syntax

Node Icon Property

Add icons to nodes using the |icon:identifier property:

[nodes]
  api:API Gateway|icon:aws-api-gateway
  db:PostgreSQL|cyl|icon:devicon-postgresql
  cache:Redis|icon:devicon-redis

Icon Identifier Format

Icon identifiers follow the pattern: [namespace-]name

• postgresql - Generic icon

• aws-lambda - AWS-namespaced icon

• azure-functions - Azure-namespaced icon

• gcp-cloud-run - GCP-namespaced icon

Standard Icon Libraries

Implementations supporting ext:icons SHOULD provide these icon sets:

Generic Technology Icons

Identifier	Description
database	Generic database
server	Generic server
cloud	Generic cloud
api	API endpoint
user	User/person
mobile	Mobile device
web	Web browser
queue	Message queue
cache	Cache/memory

AWS Icons

Identifier	Description
aws-lambda	AWS Lambda
aws-api-gateway	API Gateway
aws-s3	S3 Storage
aws-dynamodb	DynamoDB
aws-rds	RDS Database
aws-ec2	EC2 Instance
aws-ecs	ECS Container
aws-sqs	SQS Queue
aws-sns	SNS Notifications

Database Icons

Identifier	Description
postgresql	PostgreSQL
mysql	MySQL
mongodb	MongoDB
redis	Redis
elasticsearch	Elasticsearch

Service Icons

Identifier	Description
kubernetes	Kubernetes
docker	Docker
nginx	Nginx
graphql	GraphQL
auth0	Auth0

Graceful Degradation

Renderers that do not support ext:icons:

1. MUST parse |icon:... properties without error

2. MUST ignore the icon property

3. MUST render the node with its label intact

Example degradation:

db:PostgreSQL|cyl|icon:devicon-postgresql

• With ext:icons: Cylinder shape with PostgreSQL logo and "PostgreSQL" label

• Without ext:icons: Cylinder shape with "PostgreSQL" label (no icon)

Implementation Notes

Icon Resolution

Implementations may resolve icons from:

1. Bundled icon sets (recommended for offline use)

2. CDN-hosted icon libraries

3. Custom icon directories

Icon Sizing

Icons should be sized appropriately for the node:

• Default: 24x24px or similar

• Scale with node size when possible

Missing Icons

When an icon identifier is not found:

1. Log a warning (development mode)

2. Render the node without an icon

3. Do NOT fail parsing

Version History

• 1.0 (2026-01-14): Initial release