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

> Control Archify sequence diagram column spacing with column_fit and column_gap. Learn how to adjust horizontal layout for better readability in your diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/sequence.schema.json) | JSON Schema defining `column_fit` (enum) and `column_gap` (integer) properties |
| [`examples/sequence-cache-miss-request.html`](https://github.com/tt-a1i/archify/blob/main/examples/sequence-cache-miss-request.html) | Rendered example showing default column spacing |
| [`archify/test/fixtures/v1-baseline/agent-tool-call.workflow.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.