An icon can make an agent-system diagram easier to scan, but it cannot make the architecture true. Treat every icon as a label for a defined concept, not as evidence that a capability, control, or integration exists.
This is especially important in AI documentation. Terms such as memory, guardrail, evaluation, approval gate, and observability can describe very different implementations. A polished visual may imply a complete control that the deployed system does not have. The documentation must define the term, connect it to an actual component, and state the boundary.
Begin with a concept glossary
Before arranging a diagram, create a small glossary for the system being documented. For each concept, record:
- the preferred name;
- the icon filename or canonical asset ID;
- a one-sentence definition;
- the actual component, service, or process represented;
- whether the element exists, is proposed, or is outside scope;
- the owner and authoritative technical reference.
Use one name for one concept. If “memory” means a conversation summary in one diagram and a customer database in another, readers cannot tell which data is stored, where it lives, or who controls it. Use more specific labels such as “session summary,” “approved knowledge base,” or “customer system of record,” while retaining the broader icon only as a visual category.
The glossary also prevents attractive but unsupported claims. A guardrails icon should point to the actual rules, filters, permissions, or approval controls. An observability icon should point to defined logs, metrics, traces, alerts, or review records. A deployment icon should identify the environment rather than implying that the feature is live.
Build the diagram from the operational sequence
Start with the work, not the artwork. Write the system as a short sequence of inputs, decisions, actions, verification, and records. Then add icons to the nodes that need faster visual recognition.
A simple agent workflow might be:
- Prompt input — the approved request enters the system.
- Access control — software checks identity and permission.
- Agent core — the model interprets the request within its instructions.
- Tool use or API integration — the system reads or proposes a change through an allowed interface.
- Approval gate — a person or fixed policy authorizes a consequential action.
- Webhook or structured output — the result is passed in a defined format.
- Execution trace and logging — the system records what occurred.
- Fallback or retry — a bounded recovery path handles a known failure.
The sequence should show data direction and decision points. Use arrows for actual flow, not general association. Label asynchronous events, external systems, trust boundaries, and human review. If an arrow crosses from the agent into a payment, customer-record, or production system, identify the permission and verification step at that boundary.
Keep deterministic controls visually distinct
An agent can propose a decision while software enforces a rule. Show the difference. For example, the model may classify a request as refund-related; code should enforce the refund limit and account permissions. A content filter may inspect input or output, while an approval gate requires a person or policy decision before release.
Use grouping, line style, captions, or a legend to distinguish:
- model judgment;
- deterministic application logic;
- data stores;
- external tools and services;
- human actions;
- monitoring and recovery;
- proposed versus deployed components.
Do not rely on color alone for these distinctions. Readers may print the page in grayscale, view it with reduced color perception, or encounter the diagram in a context that changes its appearance. Text labels and structural grouping preserve meaning.
Use icons consistently across the document set
Create a diagram-level asset register. It should list every icon used, the version and size, its meaning in that document, and the diagrams where it appears. If the meaning changes, change the label or create a documented variant rather than silently reusing the same symbol.
Keep visual size consistent for equivalent nodes. Size can imply importance, scope, or quantity even when none was intended. Reserve size changes for a defined information hierarchy. Similarly, gold accents, borders, or glow should not be used as an unstated code for security, completion, or approval.
The current commercial AgentiScript pack contains 50 unique designs and four PNG sizes per design—1254, 1024, 512, and 256 pixels—for 200 PNG files total. The files are RGB raster PNGs with opaque dark backgrounds; transparent PNGs, SVGs, layered files, and editable sources are not included. [L1] Select the size appropriate to the layout and avoid presenting the package as vector or transparent artwork.
Make the meaning available without the image
W3C guidance requires text alternatives that convey the information or function of images. Informative images need a concise description; functional images should describe the action or destination; decorative images can use an empty text alternative. Complex diagrams need more than a short label: provide a nearby explanation or long description containing the essential relationships and sequence. [S1][S2]
For a system diagram, weak alt text is “AI workflow diagram.” A useful short alternative is “Agent support workflow with access control, human approval, and verified CRM update.” The surrounding text or long description should then state the ordered steps, exception path, and system boundaries.
Do not repeat a long caption word-for-word in alt text. Provide the shortest useful alternative in the image context and put detailed relationships in ordinary page text that everyone can reach. If an icon is purely decorative beside a visible heading, it does not need to repeat that heading.
Descriptive filenames help maintainers and can provide light contextual information to search systems. Google’s image guidance also recommends standard image elements, relevant surrounding text, useful alt text, and filenames that describe the image rather than generic camera-style names. [S3] These practices do not guarantee image discovery or ranking.
Avoid misleading visual claims
Every diagram should answer four review questions:
- Does each icon correspond to an existing or explicitly proposed element?
- Could a reader mistake a model suggestion for an enforced control?
- Are trust, data, and authorization boundaries visible?
- Can a reader understand the essential system without relying on color or the image alone?
Mark future-state elements clearly. Do not use an approval-gate icon if no approval happens. Do not use data-privacy or secret-key imagery as a substitute for describing encryption, retention, access, and secret storage. Do not use a benchmark or model-evaluation icon unless the document identifies what is measured and how results are interpreted.
When a diagram supports a commercial page, separate product facts from conceptual illustrations. The presence of an x402-payment icon does not prove that payments are active. The presence of a deployment icon does not prove production readiness. State the actual environment and verification date in the caption or accompanying text.
Review and package the diagram
Before release, perform a semantic pass and a technical pass.
In the semantic pass, check every icon against the glossary, component inventory, and system state. Ask an owner of the actual workflow to explain the diagram without prompting. If their explanation differs from the intended architecture, revise the diagram or the legend.
In the technical pass, verify filenames, dimensions, rendering at intended size, contrast, readable labels, text alternatives, link destinations, asset license, and version. Confirm that no image was stretched, cropped in a way that removes meaning, or placed on a background that hides important details. Where the original icon has an opaque dark background, design the surrounding panel deliberately rather than attempting to remove the background casually.
The current AgentiScript license permits use of the icons in finished personal and commercial end products, while prohibiting redistribution of the source icon files or a substantially similar standalone collection. [L2] The license file shipped with the customer package controls; documentation should not paraphrase it as broader permission.
A good icon system reduces the time needed to read a diagram while the accompanying text preserves precision. The visual and the technical record should agree. If they conflict, correct the visual before release.
Source notes
- [S1] W3C Web Accessibility Initiative, “Images Tutorial,” accessed 2026-09-09: https://www.w3.org/WAI/tutorials/images/
- [S2] W3C Web Accessibility Initiative, “Complex Images,” accessed 2026-09-09: https://www.w3.org/WAI/tutorials/images/complex/
- [S3] Google Search Central, “Google image SEO best practices,” accessed 2026-09-09: https://developers.google.com/search/docs/appearance/google-images
- [L1] AgentiScript customer package v1.0.1, README and manifest,
SHA-governed local release source:
/Users/colin/Documents/New project/outputs/agentiscript-first-commercial-release-20260906T181052Z/products/agentiscript-premium-ai-agent-icons-50-v1.0.1.zip - [L2] AgentiScript Commercial Icon License v1.0 in the same approved customer package. Publication, links, CTA placement, and any factual refresh require a separate approval and pre-publication QA pass.