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

> Explore the Loop or flywheel diagram type in diagram-design. Understand how this visualization illustrates reinforcing cycles and state accumulation with a shared hub.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/example-loop.html)** — Light variant with minimal chrome
- **[`assets/example-loop-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/example-loop-dark.html)** — Dark mode with token-inverted colors
- **[`assets/example-loop-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`:

```bash
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:

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md), set `data-motion-mode="loop"` to animate a decorative token circulating the ring:

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-loop.md) | Complete specification: inputs, layout math, visual grammar, anti-patterns |
| [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-geometry.py) | Automated validation of Loop geometry and accessibility |
| [`templates/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/example-loop.html)) is minimal; dark ([`example-loop-dark.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-loop-dark.html)) inverts tokens for low-light contexts; full ([`example-loop-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-loop-full.html)) adds editorial framing, summary cards, and colophon for standalone publication.