What Is the Loop (Flywheel) Diagram Type in diagram-design?

The Loop (flywheel) is a specialized diagram type that visualizes reinforcing cycles where the last step feeds back into the first, with a single shared hub that accumulates state from each iteration.

The Loop diagram type in the cathrynlavery/diagram-design repository provides an editorial-grade visual metaphor for systems where work advances clockwise around a ring while each pass writes durable state back to a central hub. It is one of 27 registered visual types defined in SKILL.md (line 99) and is particularly suited for showing operating loops, feedback mechanisms, and self-reinforcing processes.

Key Characteristics of the Loop Diagram Type

When to Use a Loop Diagram

The Loop diagram excels in scenarios requiring reinforcing cycles or flywheel visualization:

• Feedback loops where output becomes input
• Operating loops with continuous improvement
• Business flywheels (customer acquisition → satisfaction → referrals)
• Data pipelines with central logging or state management
• Product development cycles with shared knowledge bases

Structural Constraints and Budget

The Loop diagram enforces strict geometric rules defined in references/type-loop.md:

Constraint	Specification
Stations	5–8 nodes arranged clockwise
Hub	Exactly 1 central accumulator
Focal station	At most 1 station may be focal: true
Connectors	Solid ring arcs (A R R 0 0 1) clockwise; dashed radial spokes to hub

These limits ensure visual clarity—exceeding 8 stations dilutes the flywheel metaphor, while multiple hubs would fragment the central state abstraction.

Visual Geometry Implementation

In references/type-loop.md, the layout math specifies SVG arc connectors for the clockwise ring and dashed radial spokes for hub write-back. The geometry calculator positions stations equidistantly on a circle with configurable radius, while the hub sits at the visual center.

Variants and Templates

The diagram-design repository provides three production-ready HTML templates for the Loop type:

• assets/example-loop.html — Light variant with minimal chrome
• assets/example-loop-dark.html — Dark mode with token-inverted colors
• assets/example-loop-full.html — Full editorial layout with summary cards and colophon

Each template shares the same underlying SVG structure but varies in surrounding presentation context.

Generating Loop Diagrams

CLI Generation

The diagram-design CLI generates Loop diagrams via the render command with --type loop:

diagram-design render --type loop \
  --title "The self‑improving loop" \
  --subtitle "Every pass improves the shared operating record" \
  --hub name="Shared memory" sublabel="one record, every loop" \
  --stations 'Capture|Research|Decide|Act|Measure|Learn' \
  --station_w 160 --station_h 64 \
  --hub_w 200 --hub_h 104 --radius 240 --margin 64

HTML Embedding

Embed generated Loop diagrams as HTML objects:

<div class="diagram">
  <object data="example-loop.html" type="text/html"></object>
</div>

Motion and Animation

Optional animation adds visual interest without changing semantic meaning. Per animation.md, set data-motion-mode="loop" to animate a decorative token circulating the ring:

<object data="example-loop.html"
        type="text/html"
        data-motion-mode="loop"></object>

Accessibility and Validation

The Loop diagram implements the accessible SVG contract specified in SKILL.md: each <svg> carries role="img" with <title> and <desc> elements whose IDs are prefixed by the diagram slug (loop, loop-dark, etc.).

The scripts/verify-geometry.py script validates Loop-specific constraints:

• Station count within 5–8 range
• Single hub presence
• Proper connector topology (ring + spokes)
• Accessibility attribute completeness

Key Source Files

File	Purpose
references/type-loop.md	Complete specification: inputs, layout math, visual grammar, anti-patterns
SKILL.md (line 99)	Registry entry linking Loop to its reference
assets/example-loop*.html	Production templates (light, dark, full variants)
scripts/verify-geometry.py	Automated validation of Loop geometry and accessibility
templates/template.html	Base template filled by CLI render operations

Summary

• The Loop (flywheel) diagram type visualizes clockwise processes with central state accumulation
• Strict 5–8 station budget with exactly 1 hub preserves visual clarity
• Three HTML variants (light, dark, full) serve different presentation contexts
• SVG arc connectors form the ring; dashed radial spokes show hub write-back
• CLI and embeddable HTML outputs support both programmatic and manual workflows
• Accessibility compliance enforced via verify-geometry.py validation

Frequently Asked Questions

What is the maximum number of stations in a Loop diagram?

The Loop diagram type enforces a hard limit of 8 stations (minimum 5). This constraint, defined in references/type-loop.md, prevents visual overcrowding and maintains the flywheel metaphor's readability. Exceeding this limit triggers validation errors in scripts/verify-geometry.py.

Can a Loop diagram have multiple hubs?

No. The Loop type permits exactly one hub that accumulates state from all stations. Multiple hubs would fragment the central state abstraction that distinguishes flywheel diagrams from simple cyclic flows. This is validated in verify-geometry.py.

How do I enable animation in a Loop diagram?

Add the data-motion-mode="loop" attribute to your <object> or container element. As documented in animation.md, this animates a decorative token around the ring without altering the diagram's semantic content. The animation is purely presentational and degrades gracefully when motion is disabled.

What is the difference between Loop diagram variants?

The three variants—light, dark, and full—share identical SVG geometry but differ in presentation chrome. Light (example-loop.html) is minimal; dark (example-loop-dark.html) inverts tokens for low-light contexts; full (example-loop-full.html) adds editorial framing, summary cards, and colophon for standalone publication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}