How Column Fit Layout Works in Archify: Fixed vs Spread Explained

Archify's column fit layout uses meta.column_fit to control whether participant boxes stay at fixed widths or expand to fill available canvas space.

The Archify sequence diagram renderer positions participants in horizontal lanes with dimensions that depend on the column_fit setting in a diagram's JSON metadata. This article explains how the fixed (default) and spread modes differ, when to use each, and how they're implemented in the source code.

Fixed Mode: Stable Historical Coordinates

The fixed mode is the default behavior. Participant boxes are rendered at a constant 86 px width with a constant 108 px column gap. This layout ignores the canvas width entirely—adding extra space to the viewBox simply leaves empty space on the right side of the diagram.

In archify/renderers/sequence/render-sequence.mjs, the renderer resolves the mode with a fallback to fixed:

// archify/renderers/sequence/render-sequence.mjs
const columnFit = sequence.meta?.column_fit === 'spread' ? 'spread' : 'fixed';

Source: render-sequence.mjs, lines 25-30

When to use fixed mode:

• Preserving historical coordinates in existing diagrams
• Maintaining predictable, pixel-perfect layouts
• Diagrams already designed for the 86 px / 108 px spacing

Spread Mode: Responsive Canvas Filling

The spread mode derives box width and column gap from the canvas (viewBox) width. Boxes expand up to 190 px and gaps grow proportionally to fill horizontal space without changing participant order or message semantics.

The schema documents this behavior in archify/schemas/sequence.schema.json:

"column_fit": {
  "description": "Horizontal participant layout. Omit this field or use fixed for the stable 86px boxes and 108px gap. Use spread when a wide viewBox would leave unused horizontal space or meaningful participant labels do not fit the fixed boxes; spread derives wider boxes and gaps from the viewBox without changing participant order or message semantics.",
  "enum": ["fixed", "spread"]
}

Source: sequence.schema.json, lines 58-61

When to use spread mode:

• Wide viewBox would otherwise leave unused space
• Participant labels exceed the fixed 86 px box width
• You want the diagram to visually fill the available canvas

Code Examples: Column Fit in Practice

Default Fixed Behavior

// Fixed column fit (default behavior)
{
  "meta": { "title": "Demo", "viewBox": [1320, 620] },
  "participants": [
    { "id": "a", "type": "frontend", "label": "A" },
    { "id": "b", "type": "backend",  "label": "B" }
  ],
  "messages": [{ "from": "a", "to": "b", "y": 200, "label": "request" }]
}

Result: Participant boxes are 86 px wide, column gap = 108 px regardless of canvas width.

Spread Mode on Wide Canvas

// Spread column fit for full-width diagrams
{
  "meta": { "title": "Demo", "viewBox": [1320, 620], "column_fit": "spread" },
  "participants": [
    { "id": "a", "type": "frontend", "label": "A" },
    { "id": "b", "type": "backend",  "label": "B" }
  ],
  "messages": [{ "from": "a", "to": "b", "y": 200, "label": "request" }]
}

Result: Boxes widen (up to 190 px) and gaps expand to fill the viewBox width.

Handling Long Labels

// Spread mode accommodates lengthy participant names
{
  "meta": { "title": "Demo", "viewBox": [1320, 620], "column_fit": "spread" },
  "participants": [
    { "id": "a", "type": "frontend", "label": "A" },
    { "id": "b", "type": "backend",  "label": "A Very Long Participant Name That Exceeds 86px" }
  ],
  "messages": [{ "from": "a", "to": "b", "y": 200, "label": "request" }]
}

Result: The long label renders properly because spread mode enlarges the participant box. The same diagram would fail or truncate in fixed mode.

Implementation and Verification

The renderer's README provides user-facing documentation:

"Sequence diagrams use meta.column_fit: "fixed" by default so existing documents keep their historical coordinates. Use "spread" when a wide viewBox would otherwise leave empty space on the right or when meaningful participant labels do not fit the fixed 86px boxes."

Source: README.md, lines 73-80

The Archify test suite in archify/test/sequence-column-fit.test.mjs validates these behaviors:

• Fixed maintains 108 px gap regardless of canvas width
• Spread widens boxes, increases gaps, respects side margins, and stays within viewBox
• Opt-in behavior: omitting column_fit yields identical output to explicit "fixed"

Source: sequence-column-fit.test.mjs, lines 68-84

Key Source Files

File	Purpose
archify/renderers/sequence/render-sequence.mjs	Core renderer; determines columnFit and computes dimensions
archify/schemas/sequence.schema.json	JSON Schema definition for column_fit property
archify/renderers/sequence/README.md	User documentation for column fit options
archify/test/sequence-column-fit.test.mjs	Automated tests verifying fixed and spread behavior

Summary

• Fixed mode provides stable 86 px boxes and 108 px gaps—ideal for existing diagrams and pixel-precise layouts
• Spread mode scales boxes up to 190 px and expands gaps to fill the viewBox—use for wide canvases or long labels
• Set meta.column_fit to "spread" to enable responsive layout; omit or set to "fixed" for default behavior
• The renderer in render-sequence.mjs uses a simple ternary to resolve the mode at lines 25-30

Frequently Asked Questions

What is the default column fit mode in Archify?

Fixed mode is the default. If you omit column_fit from your diagram's metadata or set it to any value other than "spread", Archify uses fixed dimensions: 86 px participant boxes with 108 px column gaps. This default preserves backward compatibility with existing diagrams.

How do I switch to spread mode in my Archify diagram?

Add "column_fit": "spread" to your diagram's meta object. The spread mode automatically calculates box widths and gaps based on your viewBox width, allowing boxes to grow up to 190 px and gaps to expand proportionally.

Why would fixed column fit leave empty space on the right?

Fixed mode uses constant dimensions regardless of canvas size. If your viewBox width exceeds what the fixed boxes and gaps require, the remaining space stays empty. This is intentional—it ensures historical diagrams maintain their exact coordinates rather than stretching unexpectedly.

Can spread mode handle participant labels longer than 86 characters?

Yes, spread mode accommodates longer labels. While the limit is 190 px (not characters), spread mode's elastic box sizing provides significantly more room than fixed mode's rigid 86 px constraint. For extremely long labels, consider abbreviations or multi-line formatting regardless of mode.

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