# Diagram Design Advanced Features: A Complete Guide to Brand-Aware, Semantic Diagramming

> Explore advanced Diagram Design features like brand-aware styling and semantic patterns. Create editorial-quality visuals for multiple agent platforms with this comprehensive guide.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-20

---

**Diagram Design is a full-featured design system that enables agents to produce editorial-quality visuals with brand-aware styling, semantic behavior patterns, and optional accessible motion—all while keeping outputs self-contained and portable across Claude Code, Codex, Factory Droid, Pi, and other agent platforms.**

Unlike static diagram libraries, Diagram Design treats diagrams as **behavior-driven, brand-aware artifacts**. The system combines semantic routing, automatic brand extraction, and reusable primitives to transform how technical teams create and share visual documentation. This guide covers the eight advanced capabilities that distinguish Diagram Design from conventional tools.

## Loop Diagrams and Shared-Memory Hubs

The **Loop diagram type** (also called "flywheel") models reinforcing cycles and shared-state hubs in a single visual element. This makes it ideal for illustrating self-improving processes, feedback loops, or circular dependencies where state accumulates at a central hub.

To create a loop diagram, reference the `loop` type directly:

```text
Make a loop diagram of the CI/CD pipeline with motion=step.

```

The loop implementation is defined in [[`skills/diagram-design/references/type-loop.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-loop.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-loop.md), which specifies the visual grammar for hub nodes, directional flow indicators, and cycle completion markers.

## Semantic System Patterns

Before any layout is chosen, Diagram Design applies one of **seven routed semantic patterns** that describe behavior independently of visual representation:

| Pattern | Use Case |
|---------|----------|
| **Queues** | FIFO/LIFO processing stages |
| **Repeated stages** | Iterative or cyclical workflows |
| **Transformation pipelines** | Data or code transformation sequences |
| **Policy traces** | Decision-path auditing |
| **Security layers** | Defense-in-depth architectures |
| **Governance catalogs** | Compliance control inventories |
| **Compensating controls** | Risk mitigation pairings |

These patterns live in [[`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). By separating **what a diagram means** from **how it looks**, the same behavioral logic can be rendered as a flowchart, architecture diagram, or timeline without rewriting the underlying structure.

## Optional Accessible Motion

Motion in Diagram Design is not a separate diagram type—it is an **optional layer** that can be added to any diagram. Four motion modes are supported:

- **`none`** — Static rendering (default)
- **`reveal`** — Progressive disclosure of elements
- **`step`** — Step-by-step walkthrough with manual advancement
- **`loop`** — Continuous animation for cyclic processes

Motion implementations in [[`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) enforce strict accessibility contracts: static first frames for all animations, deterministic timing functions, ARIA labels for screen readers, and automatic `prefers-reduced-motion` fallback. This ensures animated diagrams remain usable in documentation, presentations, and compliance contexts.

## Automatic Brand Onboarding

The **brand onboarding** feature fetches a website, extracts its dominant palette and font stack, and maps them to semantic design tokens. The process:

1. Scrapes the target URL for CSS color and typography definitions
2. Maps extracted values to tokens: `paper` (background), `ink` (text), `accent` (highlights), `muted` (secondary), `success`, `warning`, `error`
3. Stores the result in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) for the project

Run once per project:

```text
/diagram-design:profile onboard https://example.com

```

All subsequent diagrams automatically inherit these brand tokens. The onboarding specification is documented in [[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md).

## Import and Redraw from draw.io and Mermaid

Diagram Design can **ingest existing diagrams** from draw.io and Mermaid, parse them into a structured intermediate representation, and redraw them using its editorial style system. The import pipeline respects four tunable "dials":

| Dial | Options | Effect |
|------|---------|--------|
| **format** | `native`, `svg`, `png` | Output format |
| **size** | `slide-4x3`, `slide-16x9`, `a4-portrait`, `a4-landscape`, `social-square` | Canvas dimensions |
| **detail** | `minimal`, `balanced`, `comprehensive` | Information density |
| **audience** | `executive`, `technical`, `mixed` | Annotation depth |

Import commands:

```text
/diagram-design:import-drawio path/to/infra.drawio --size=slide-16x9 --detail=balanced
/diagram-design:import-mermaid path/to/flow.mmd --audience=executive

```

The process produces a **fidelity ledger** describing what was preserved, collapsed, or dropped. Implementation details are in [[`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md) and [[`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md).

## Profile Library for Multi-Brand Workflows

Named **profiles** enable parallel workspaces with distinct brand tokens without overwriting shared style guides. Profiles are stored as:

```

~/.diagram-design/profiles/<slug>.md

```

To activate a profile in a project, create a marker file:

```text

# In the client repo

echo "profile: acme" > .diagram-design

```

The skill automatically loads `~/.diagram-design/profiles/acme.md` when processing diagrams in that directory. This supports agency workflows where multiple client brands must coexist without cross-contamination. Profile mechanics are defined in [[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md).

## Primitives for Annotation, Sketchy Style, and Terminal Rendering

Diagram Design ships **reusable primitives** that can be dropped into any diagram:

- **Annotation callouts** — Contextual notes with leader lines and semantic coloring ([[`primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-annotation.md))
- **Sketchy filters** — Hand-drawn appearance for informal or draft visuals ([[`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md))
- **Terminal-style code blocks** — Monospace rendering with syntax highlighting for CLI or code-centric diagrams

These primitives compose with any diagram type, enabling mixed-fidelity presentations where polished architecture diagrams include hand-drawn annotations or terminal excerpts.

## Export Utilities for Production Use

Built-in export commands generate production-ready assets:

```text
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png --dpi=300

```

Export features in [[`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) guarantee:

- Clean SVG with embedded fonts
- High-resolution PNG via Playwright headless rendering
- Preservation of accessibility metadata
- Deterministic output for CI/CD pipelines

## Summary

- **Loop diagrams** model reinforcing cycles with shared-state hubs for self-improving processes
- **Seven semantic patterns** separate behavior from visual representation, enabling layout reuse
- **Four motion modes** (`none`, `reveal`, `step`, `loop`) add accessible animation to any diagram
- **Brand onboarding** extracts palettes and fonts from websites, mapping to semantic tokens
- **Import pipelines** for draw.io and Mermaid include fidelity ledgers and tunable output dials
- **Profile library** supports multi-brand workflows via marker files and isolated storage
- **Reusable primitives** provide annotation, sketchy styling, and terminal rendering
- **Export utilities** produce SVG and PNG with embedded fonts and accessibility metadata

## Frequently Asked Questions

### How does Diagram Design handle brand consistency across multiple projects?

Diagram Design uses named profiles stored in `~/.diagram-design/profiles/<slug>.md`. Each project references its profile via a `.diagram-design` marker file containing `profile: <slug>`. This isolates brand tokens so switching between client projects requires no manual reconfiguration—agents automatically load the correct style guide.

### Can I add animation to an existing static diagram without rebuilding it?

Yes. Motion is an optional layer controlled by the `motion` parameter. Set `motion=reveal`, `motion=step`, or `motion=loop` when requesting a diagram revision. The animation system preserves all semantic content and adds deterministic timing with full accessibility support, including reduced-motion fallbacks for users with vestibular disorders.

### What information is lost when importing from draw.io or Mermaid?

The import pipeline generates a **fidelity ledger** that explicitly documents preserved, collapsed, and dropped elements. Loss typically occurs with: proprietary draw.io shapes without semantic equivalents, Mermaid subgraph nesting beyond three levels, and inline styling that conflicts with the onboarded brand tokens. Use `--detail=comprehensive` to minimize loss, or `--detail=minimal` for executive summaries.