Archify Sequence Diagram Column Spacing: Controlling Horizontal Layout with `column_fit` and `column_gap`

Archify provides two JSON properties—column_fit (enum: tight, loose, balanced) and column_gap (integer pixels)—to control how much horizontal space separates participants in sequence diagrams.

Archify's sequence-diagram renderer gives you precise control over column spacing through its schema-based configuration. Whether you need compact diagrams for simple flows or generous spacing for complex interactions, you can tune the horizontal layout without touching any rendering code. The column_fit and column_gap properties in archify/schemas/sequence.schema.json determine how participant columns are distributed across the diagram canvas.

The Two Column Spacing Controls in Archify

Archify exposes two complementary properties for horizontal layout control. You can use them independently or together, with column_gap taking precedence when both are present.

column_fit: Preset Packing Modes

The column_fit property selects from three predefined spacing strategies:

• tight — Minimizes gaps between columns, ideal for dense diagrams with few participants
• loose — Inserts extra horizontal space for improved readability in complex diagrams
• balanced — Lets Archify automatically select optimal spacing based on content

When column_fit is used alone, Archify applies a default gap value appropriate to the selected mode.

column_gap: Pixel-Precise Control

For exact spacing requirements, column_gap accepts any non-negative integer (e.g., 0, 10, 40). This value specifies the gap in pixels between adjacent participant columns.

If column_gap appears in your diagram specification, it overrides the automatic gap implied by column_fit. You can combine both properties—column_gap always wins.

How Column Spacing Affects Diagram Rendering

According to the Archify source code, column spacing settings influence three rendering aspects:

• Participant ordering — Columns follow the sequence defined in participants, but their horizontal distance varies
• Arrow routing — Wider gaps provide more room for orthogonal arrows without overlaps
• Label placement — Looser layouts reduce label collision risk on lifelines

These effects are implemented in the rendering pipeline defined by archify/schemas/sequence.schema.json.

Code Examples: Controlling Column Spacing in Archify

Each example below demonstrates a specific spacing approach. All properties belong at the top level of your sequence diagram JSON.

Tight Packing for Compact Diagrams

{
  "type": "sequence",
  "participants": [
    { "id": "client", "label": "Client" },
    { "id": "api",    "label": "API Server" },
    { "id": "db",     "label": "Database" }
  ],
  "messages": [
    { "from": "client", "to": "api",    "label": "request()" },
    { "from": "api",    "to": "db",     "label": "query()" },
    { "from": "db",     "to": "api",    "label": "result" },
    { "from": "api",    "to": "client", "label": "response()" }
  ],
  "column_fit": "tight"
}

This configuration packs the three participants tightly—useful for short request-response flows where screen real estate matters.

Loose Spacing for Readability

{
  "type": "sequence",
  "participants": [ 
    { "id": "client", "label": "Client" },
    { "id": "api",    "label": "API Server" },
    { "id": "db",     "label": "Database" }
  ],
  "messages": [ 
    { "from": "client", "to": "api",    "label": "request()" },
    { "from": "api",    "to": "db",     "label": "query()" },
    { "from": "db",     "to": "api",    "label": "result" },
    { "from": "api",    "to": "client", "label": "response()" }
  ],
  "column_fit": "loose"
}

The loose mode spreads participants horizontally, providing visual breathing room for complex interactions with many messages or long labels.

Custom Pixel Gap

{
  "type": "sequence",
  "participants": [ 
    { "id": "client", "label": "Client" },
    { "id": "api",    "label": "API Server" },
    { "id": "db",     "label": "Database" }
  ],
  "messages": [ 
    { "from": "client", "to": "api",    "label": "request()" },
    { "from": "api",    "to": "db",     "label": "query()" },
    { "from": "db",     "to": "api",    "label": "result" },
    { "from": "api",    "to": "client", "label": "response()" }
  ],
  "column_gap": 40
}

Setting column_gap to 40 establishes a 40 px gap regardless of any column_fit value. This is the approach to use when you need predictable, document-wide consistency.

Combining Both Properties

{
  "type": "sequence",
  "participants": [ 
    { "id": "client", "label": "Client" },
    { "id": "api",    "label": "API Server" },
    { "id": "db",     "label": "Database" }
  ],
  "messages": [ 
    { "from": "client", "to": "api",    "label": "request()" },
    { "from": "api",    "to": "db",     "label": "query()" },
    { "from": "db",     "to": "api",    "label": "result" },
    { "from": "api",    "to": "client", "label": "response()" }
  ],
  "column_fit": "tight",
  "column_gap": 30
}

Here column_gap: 30 overrides the tight mode's default spacing. This pattern is useful when you want self-documenting configuration—column_fit signals intent while column_gap enforces the exact measurement.

Source Files for Column Spacing in Archify

These files in the tt-a1i/archify repository define and demonstrate column spacing behavior:

File	Purpose
archify/schemas/sequence.schema.json	JSON Schema defining column_fit (enum) and column_gap (integer) properties
examples/sequence-cache-miss-request.html	Rendered example showing default column spacing
archify/test/fixtures/v1-baseline/agent-tool-call.workflow.json	Production workflow using column_fit for layout control

The schema file is the authoritative source for valid property values and type constraints.

Summary

• Archify sequence diagrams expose column_fit (tight/loose/balanced) and column_gap (pixel integer) for horizontal layout control
• column_gap overrides column_fit when both are specified
• Both properties live in the sequence diagram JSON, validated against archify/schemas/sequence.schema.json
• Spacing choices affect arrow routing efficiency and label collision avoidance
• Use tight for compact diagrams, loose for readability, or column_gap for pixel-exact requirements

Frequently Asked Questions

What happens if I specify both column_fit and column_gap?

column_gap takes precedence. Archify applies your exact pixel value while ignoring the automatic gap that column_fit would normally provide. The column_fit value still documents your layout intent but does not affect rendering.

Can I set column_gap to zero for overlapping columns?

Yes. column_gap accepts 0, which eliminates space between participant lifelines. This produces extremely compact diagrams but may cause arrow routing and label placement issues in complex sequences.

Where are the default gap values for each column_fit mode defined?

The default gaps are implementation details in Archify's rendering engine, not exposed in the JSON Schema. The schema at archify/schemas/sequence.schema.json only validates that column_fit is one of the three allowed strings. To observe typical defaults, compare rendered output in examples/sequence-cache-miss-request.html against diagrams with explicit column_gap values.

Does column_fit: "balanced" produce deterministic spacing?

Balanced mode applies Archify's internal heuristic based on participant count, message density, and label lengths. Results are deterministic for identical inputs but may vary across Archify versions as the algorithm evolves. For stable, reproducible spacing, specify column_gap explicitly.

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