name: ascii-diagrams
description: Comprehensive ASCII diagram generation, modification, and interpretation for technical documentation. Supports web/frontend design, sequence diagrams, ER diagrams, network topology, timelines, UML class diagrams, component interaction, container deployment, swimlanes, system architecture, control flow, data structures, file systems, UI interfaces, and mathematical concepts. Use when creating or modifying diagrams for markdown docs, code comments, wireframes, or extracting structural information from existing diagrams.

ASCII Diagram Generator and Editor

Generate, modify, and interpret high-quality ASCII diagrams across comprehensive categories for technical documentation and visualization.

Core Capabilities

This skill provides professional ASCII diagram generation across ten major categories, each with dedicated reference documentation containing patterns, best practices, and comprehensive examples.

The skill supports web interface and frontend design with complete patterns for landing pages, SaaS dashboards, e-commerce interfaces, responsive layouts, and modern UI components. Sequence and interaction diagrams enable documentation of API flows, authentication sequences, microservice communication, and async messaging patterns. Entity relationship and database schema diagrams support data modeling with crow's foot notation, normalization patterns, and constraint visualization.

Network topology and infrastructure diagrams cover cloud architectures, network segmentation, multi-region deployments, VPN topologies, and protocol stacks. Timeline and project planning diagrams facilitate schedule visualization with Gantt charts, milestone tracking, sprint planning, and dependency mapping. UML class diagrams document object-oriented designs including inheritance hierarchies, interface definitions, composition patterns, and design patterns.

Component interaction and integration patterns illustrate request-response flows, publish-subscribe messaging, service mesh architectures, API gateways, event sourcing, and circuit breakers. Container and deployment diagrams following C4 model principles show system context, container views, component organization, and cloud deployment topologies. Swimlane and process flow diagrams map cross-functional workflows, approval processes, customer journeys, and system integration flows. System and software architecture diagrams visualize microservices, layered architectures, hexagonal architecture, CQRS patterns, and event-driven systems.

The skill also provides modification capabilities for existing diagrams, allowing users to add components, remove elements, restructure layouts, update labels, change connections, or refine alignment while preserving the original diagram's style and conventions.

Reference Documentation

The skill provides comprehensive reference files organized by diagram category and cross-cutting quality concerns. Each reference contains comprehensive patterns, best practices, detailed examples, and guidance on when to use each diagram type.

Quality Assurance Reference

ASCII Art Validation and Quality Assurance provides critical guidance on preventing alignment issues, validating diagram correctness, and repairing malformed ASCII art. This reference explains root causes of rendering failures including tabs versus spaces, font issues, and character set problems. It documents mandatory quality standards including spaces-only whitespace, ASCII character restrictions, and monospace font assumptions. The reference provides systematic validation procedures for character compliance, alignment verification, and cross-platform rendering tests. It also includes repair procedures for removing tabs, correcting alignment, and normalizing character sets. Consult this reference before generating any diagram to understand quality constraints and after generation to validate correctness.

Utility Scripts

The scripts directory contains executable Python tools for automated quality assurance. The validate_ascii.py script checks diagrams for tab characters, non-ASCII characters, and CRLF line endings, reporting any compliance violations. The convert_to_ascii.py script converts Unicode box-drawing characters and other non-ASCII characters to their ASCII equivalents, enabling repair of diagrams that contain compatibility issues. Both scripts support single files and directory processing with configurable file extension filters. See scripts/README.md for detailed usage instructions.

Core Design References

Web Interface and Frontend Design covers landing pages, SaaS dashboards, e-commerce patterns, admin panels, responsive layouts, form design, navigation patterns, and UI component libraries. This reference is essential for creating web application wireframes, responsive designs, and modern frontend mockups.

Sequence and Interaction Diagrams documents API interactions, authentication flows, request-response patterns, async messaging, microservices communication, error handling flows, and retry logic. Use this reference when illustrating temporal ordering of system interactions or documenting communication protocols.

Entity Relationship and Database Schema provides patterns for crow's foot notation, complex relationships, one-to-one, many-to-many, database schemas with indexes, inheritance patterns, temporal data, and denormalized views. This reference supports data modeling and database design documentation.

Infrastructure and Planning References

Network Topology and Infrastructure covers network layouts, cloud architectures, network segmentation, multi-region deployments, VPN topologies, protocol stacks, and Kubernetes cluster networks. Essential for documenting infrastructure architecture and deployment topologies.

Timeline and Project Planning includes basic timelines, horizontal Gantt charts, project phases with milestones, dependency tracking, sprint timelines, historical timelines, release schedules, roadmaps, and critical path analysis. Use this reference for project management and schedule visualization.

UML Class Diagrams documents class structures, inheritance hierarchies, interface implementation, composition and aggregation, associations with multiplicity, design patterns like Observer and Factory, package diagrams, and generic classes. This reference supports object-oriented design documentation.

Integration and Deployment References

Component Interaction and Integration Patterns covers request-response patterns, publish-subscribe messaging, message queues, service mesh architecture, API gateways, event sourcing, SAGA patterns, circuit breakers, and event-driven microservices. Use this reference when documenting distributed system communication.

Container and Deployment Diagrams follows C4 model principles with system context, container diagrams, Docker Compose architecture, Kubernetes deployments, cloud deployment architecture, and infrastructure as code layouts. Essential for documenting containerization and deployment strategies.

Swimlane and Process Flow includes basic swimlanes, approval workflows, customer journey maps, system integration processes, document approval flows, and multi-system processes. Use this reference for cross-functional process documentation and responsibility mapping.

System and Software Architecture provides microservices architecture patterns, layered architecture, hexagonal architecture, event-driven architecture, CQRS patterns, and plugin architectures. This reference supports high-level system design documentation.

Generation Workflow

When generating diagrams from natural language descriptions, follow this systematic approach to ensure high-quality, appropriate visualizations that render correctly across all platforms.

Step 1: Understand the Request

Parse the user's description to identify diagram type, key components, relationships, and required detail level. Common requests include creating microservices architectures with specific services and protocols, wireframing web interfaces with particular layouts and components, showing state machines for authentication or other processes, visualizing git repository structures, documenting API interaction sequences, or illustrating database schemas with relationships.

When descriptions reference code repositories or projects, examine the structure first to identify actual components, dependencies, and patterns before generating diagrams. For git diagrams, analyze branch structure and commit history when available. For UI wireframes, consider the target platform to apply appropriate conventions for web, mobile, or desktop interfaces.

Step 2: Select Reference Documentation

Identify the most relevant reference file based on the diagram type requested. Before beginning diagram generation, consult the validation and quality reference to understand mandatory constraints including spaces-only whitespace, ASCII character restrictions, and cross-platform rendering requirements. These quality standards must be maintained throughout diagram generation to ensure consistent rendering.

Web and frontend design requests use the 01-web-frontend-design reference. API interactions and temporal sequences use 02-sequence-interaction. Database schemas and entity relationships use 03-er-database-schema. Infrastructure and network diagrams use 04-network-topology. Project schedules and timelines use 05-timeline-gantt. Object-oriented designs use 06-uml-class-diagrams. Distributed system messaging uses 07-component-interaction. Deployment and containerization uses 08-container-deployment. Cross-functional processes use 09-swimlane-process. High-level system architecture uses 10-system-architecture.

Consult the selected reference file for established patterns, conventions, and examples specific to the diagram type. Use spaces exclusively for all positioning, never tabs. Restrict all characters to the standard ASCII printable range of 32 through 126, avoiding Unicode box-drawing characters. Design for monospace font rendering with consistent line endings using LF only.

Step 3: Plan the Layout

Before generating the diagram, plan the spatial layout to ensure proper alignment, minimize line crossings, and maintain visual clarity. Consider the diagram's natural orientation based on whether it represents hierarchy with top-down flow, sequence with left-right temporal progression, state transitions with circular or networked relationships, user interface with structured grid layouts, or infrastructure with layered or grouped arrangements.

Group related components visually and use whitespace effectively to separate logical sections. For complex diagrams, determine whether to create a single comprehensive view or multiple focused diagrams showing different aspects or abstraction levels.

Step 4: Generate the Diagram

Create the ASCII diagram following the patterns and conventions documented in the relevant reference file. Use consistent spacing and alignment to ensure proper rendering in monospace fonts. Label all components clearly and concisely including entity names, state labels, process steps, file paths, API endpoints, or component identifiers as appropriate for the diagram type.

Use directional arrows to show data flow, dependencies, state transitions, control flow, or temporal ordering. Include edge labels when they provide essential context such as protocol types HTTP or gRPC, relationship names owns or implements, event triggers button_click or timeout, transition conditions authenticated or failed, or multiplicity indicators one-to-many or many-to-many.

Maintain visual hierarchy through box sizes, nesting, or indentation to show containment, importance, or abstraction levels. Keep diagrams readable by limiting complexity and avoiding excessive nesting beyond three to four levels for most diagram types.

Step 5: Add Context

After the diagram, provide a brief explanation highlighting key architectural decisions, important relationships, non-obvious behaviors, or critical constraints that complement the visual without repeating what is already clear. This context helps readers understand the significance of the structure rather than merely describing its visual elements.

Modification Workflow

When modifying existing ASCII diagrams, preserve the original structure and style while implementing requested changes systematically.

Step 1: Analyze the Existing Diagram

Examine the current diagram to understand its structure including diagram type and category, character set usage such as basic ASCII or Unicode box-drawing, overall layout direction and spacing patterns, alignment conventions, and all existing components with their relationships. Identify which reference file would apply to this diagram type for guidance on maintaining appropriate conventions.

Step 2: Determine Modification Scope

Classify the modification type based on the request. Adding new components requires finding appropriate positions that maintain visual balance and existing connections. Removing elements necessitates adjusting surrounding components and reconnecting affected relationships. Restructuring layout involves reorganizing spatial arrangement while preserving all relationships and information. Updating labels or annotations changes text while maintaining alignment and visual consistency. Changing connections modifies arrows, lines, or relationships between components while preserving overall structure.

Step 3: Implement Changes Carefully

Make requested modifications while maintaining consistency with the existing diagram's conventions. Preserve the character set being used throughout. Maintain the same spacing and alignment patterns established in the original. Keep the same visual hierarchy and component representation style. Ensure all connections and relationships remain clear and unambiguous. Verify the modified diagram still renders correctly in monospace fonts.

Step 4: Validate and Refine

After implementing changes, review the modified diagram for correctness. Check that all new or modified components align properly with existing elements. Verify that line crossings have not been inadvertently introduced or worsened. Ensure all labels remain clear and readable. Confirm the modification addresses the user's request completely. Make necessary refinements to improve overall visual quality while staying true to the original style.

Interpretation Workflow

When interpreting or extracting information from existing ASCII diagrams, provide comprehensive structural analysis and semantic understanding.

Identify the diagram type by recognizing characteristic patterns such as boxes and arrows for architecture diagrams, sequence of interactions for sequence diagrams, entities with relationships for ER diagrams, swimlanes with process flows for cross-functional workflows, layered structures for software architectures, or specialized notation for mathematical diagrams. Consult the appropriate reference file to understand conventions specific to the identified diagram type.

Parse the diagram structure by identifying all components including boxes, nodes, states, entities, or other visual elements, then mapping all connections including lines, arrows, transitions, relationships, or edges with their directionality and labels. For complex diagrams, recognize hierarchical relationships, groupings, or layering that indicates structural organization.

Extract semantic information by determining component types and their roles in the system, understanding relationship semantics such as inheritance, composition, aggregation, or message passing, identifying data flow or control flow patterns, recognizing state transitions and their triggering events or conditions, understanding temporal ordering in sequence diagrams, and recognizing architectural or design patterns such as microservices, layered architecture, or observer pattern.

Provide a structured description including the overall purpose and context, key components with their functions and responsibilities, relationships and communication patterns, important constraints or business rules, architectural or design decisions evident in the structure, and any notable patterns or anti-patterns present in the design.

Quality Guidelines

Generated and modified diagrams must meet professional standards for visual clarity and technical accuracy while adhering to strict quality constraints that ensure consistent rendering across all platforms and editors. Consult the validation and quality reference for comprehensive guidance on preventing and fixing alignment issues.

Diagrams must use spaces exclusively for all alignment and positioning with zero tab characters present anywhere in the structure. Tab characters render with variable width based on editor configuration, causing diagrams to appear perfectly aligned in one environment while completely broken in another. This quality standard is non-negotiable for cross-platform compatibility.

All characters must fall within the standard ASCII printable range of 32 through 126 inclusive. This restriction includes avoiding Unicode box-drawing characters such as + - + | + + + + + + + despite their visual appeal. While Unicode box-drawing can produce more polished appearance, these characters introduce font rendering inconsistencies and compatibility issues across different terminals, editors, and documentation systems. Use ASCII alternatives including plus + for corners, minus - for horizontal lines, pipe | for vertical lines, and slash / or backslash \ for diagonal connections.

Diagrams should be well-aligned with all elements properly positioned in the monospace character grid. Vertical elements such as box edges, column separators, or tree branches must appear in exactly the same column position throughout their vertical run with zero variance. Horizontal elements such as box borders or separator lines must maintain consistent width across corresponding structures. Count characters precisely to ensure exact positioning.

Clear labeling with descriptive names for all components is essential. Component names, state labels, process steps, entity identifiers, and edge labels should be concise yet meaningful. Avoid abbreviations unless they are standard within the domain such as HTTP, API, or DB. Include meaningful edge labels showing protocols, relationships, events, conditions, or multiplicities where they clarify the diagram semantics.

Visual balance through effective use of whitespace and logical grouping improves diagram comprehension. Group related components visually using whitespace separation or containing structures. Avoid cramming too many elements into limited space, which reduces clarity and makes relationships harder to understand. Use consistent spacing patterns throughout each diagram to establish visual rhythm and make the structure more scannable.

Appropriate level of detail shows necessary information without overwhelming complexity. Focus on the most important components and relationships relevant to the diagram's purpose. Omit implementation details that would clutter the diagram without adding semantic value. Consider whether a single comprehensive diagram or multiple focused diagrams better serves the documentation goals. Complex systems often benefit from multiple views at different abstraction levels rather than one massive diagram attempting to show everything.

Proper formatting ensures diagrams render correctly across different monospace fonts and terminal widths. Test rendering in common monospace fonts including Courier, Consolas, Monaco, and JetBrains Mono to verify consistent appearance. Keep line lengths reasonable, typically 80 columns maximum for broad compatibility, with 120 columns as an absolute maximum for complex diagrams requiring additional width. Design diagrams to degrade gracefully if viewed in narrow terminals, with the most critical information visible even at constrained widths.

Avoid common pitfalls that undermine diagram quality and cross-platform compatibility. Never mix tabs and spaces within a diagram or anywhere in the file containing the diagram. Do not use Unicode box-drawing characters or any characters outside the ASCII printable range. Prevent unnecessary line crossings that reduce clarity by planning layout carefully before generation. Maintain consistent spacing and character usage throughout rather than varying styles within a single diagram. Avoid trailing whitespace at line endings which many editors automatically strip, potentially breaking alignment that depends on those spaces.

When modifying diagrams, maintain visual consistency with the original style, character set, and formatting conventions. Avoid introducing tabs if the original used spaces, Unicode characters if the original was ASCII-only, or different spacing patterns that clash with existing alignment. Ensure modifications integrate seamlessly rather than appearing as additions from a different source or tool.

Using Reference Documentation

Each reference file follows a consistent structure to facilitate quick lookup and comprehensive understanding. Reference files begin with a clear statement of when to use that diagram type, helping you determine if the reference applies to your current task. Comprehensive examples demonstrate common patterns within the category, ranging from simple to complex scenarios. Best practices sections provide guidance on layout, labeling, visual hierarchy, and avoiding common mistakes specific to that diagram type.

When generating diagrams, review the relevant reference file before starting to ensure adherence to established patterns and conventions. Use the examples as templates that can be adapted to your specific requirements. Apply the best practices to ensure professional quality output that will be immediately recognizable and understandable to readers familiar with standard technical documentation.

Reference files are designed to be self-contained, allowing you to focus on a single category without needing to cross-reference multiple files during generation. However, complex documentation projects may require multiple diagram types, in which case you should consult each relevant reference file to ensure consistency across your entire documentation set.