The "Diagram Design" project is a sophisticated, agent-centric skill set designed to generate 39 editorial-quality diagram types across various platforms, including Claude Code, Codex, and Factory Droid. Moving away from generic "rounded-box" templates, the tool emphasizes semantic clarity, brand integration, and high-fidelity output without relying on external dependencies like Figma or heavy JavaScript.

Core Methodology and Technical Architecture

The system operates on a "progressive disclosure" architecture, where the agent loads minimal logic initially and dynamically fetches specific references (types, semantic patterns, or animation contracts) based on the user's intent.

1. Semantic Routing and Layout
Unlike standard graphing libraries, this system separates behavior from visual form. It defines seven primary "semantic patterns" (e.g., queues, policy traces, trust boundaries) that determine the diagram's logic before the visual type is selected. This allows for consistent representation across different diagram types without inflating the number of total visual templates.

2. Brand-Driven Styling
The system automates aesthetic alignment through an onboarding mechanism:

• Brand Extraction: The agent parses a provided URL to extract dominant palette values and font stacks.
• Semantic Mapping: Detected colors are mapped to roles: paper (background), ink (text), muted (captions), paper-2 (containers), and accent (focal elements).
• Automated Validation: The system enforces WCAG AA contrast ratios ($C > 4.5:1$ for small text) for all generated tokens. If a site's colors fail this, the system automatically suggests adjustments. These tokens are stored in references/style-guide.md, which acts as the single source of truth for all downstream rendering.

3. Data Import and Transformation
The system includes specialized parsers (drawio_extract.py, mermaid_extract.py) to convert legacy formats into a structured Intermediate Representation (IR). This process strips proprietary coordinates and spaghetti-style connectors, rebuilding the diagram based on a strict 4px grid. A "fidelity ledger" reports the transformation process, noting how nodes were collapsed or merged to maintain "editorial density" (a target of 4/10 nodes).

4. Rendering and Quality Assurance

• Output: The default output is self-contained HTML/SVG, free of JS or remote asset dependencies.
• Accessibility: Every SVG includes $role="img"$, valid aria-labelledby attributes, and $<title>$/$<desc>$ slots.
• Geometric Linting: A rigorous CI pipeline validates output using headless Chromium. It performs:
  • Paint-based Clipping: Measures spill outside the SVG bounds to prevent cut-off text.
  • Treemap Integrity: Validates that the visual area $A$ accurately represents the input value $V$ such that $\frac{A_{i}}{\sum A} \approx \frac{V_{i}}{\sum V}$.
  • Label Placement: Ensures labels do not overlap subsequent nodes to avoid clipping during fill-rendering.

5. Animation and Motion
Animation is an optional, modular layer defined in animation.md. It supports reveal, step, and loop modes. To ensure accessibility, reduced-motion preferences are honored, and the system prevents arbitrary script injection by only allowing the pre-reviewed, deterministic motion controller.