Sequence Diagram Column Fitting Options in Archify: Fixed vs. Spread Layout Modes

Archify offers two sequence diagram column fitting options—fixed (default) and spread—that control how participant columns are spaced horizontally via the meta.column_fit property.

Archify's sequence diagram renderer provides configurable layout modes for controlling column spacing. This guide covers the column_fit options available in the meta object, their behavior, and when to use each mode according to the tt-a1i/archify source code.

Understanding the Column Fit Options

The column_fit property accepts two string values that determine how participant columns distribute across the diagram's horizontal space.

Fixed Layout (Default)

The fixed layout maintains consistent, compact spacing regardless of viewBox width.

• Participant boxes render at 86 px width
• Fixed gap of 108 px between columns
• Preserves author-defined column order
• Guarantees byte-stable geometry across renders
• Applied automatically when meta.column_fit is omitted

This mode ensures backward-compatible rendering and predictable output for existing diagrams.

Spread Layout

The spread layout adapts column spacing to fill the available viewBox width.

• Columns stretch proportionally to fill horizontal space
• Derives larger participant boxes and gaps from viewBox dimensions
• Maintains participant order and message semantics
• Eliminates large empty margins on wide viewBoxes

Use this mode when participant labels exceed fixed-size boxes or when the authored viewBox is significantly wider than the content.

Configuring Column Fit in Diagram JSON

The column_fit property resides inside the meta object of a sequence diagram schema, as defined in archify/schemas/sequence.schema.json (lines 50-53).

Default Fixed Layout (Omitted)

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "User Login Flow"
  },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client" },
    { "id": "auth",   "type": "backend",  "label": "Auth Service" }
  ],
  "messages": [
    { "from": "client", "to": "auth", "y": 200, "label": "POST /login" }
  ]
}

Explicit Spread Layout

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "User Login Flow",
    "column_fit": "spread"
  },
  "participants": [
    { "id": "client", "type": "frontend", "label": "Client Application" },
    { "id": "auth",   "type": "backend",  "label": "Authentication Service" },
    { "id": "db",     "type": "database", "label": "User DB" }
  ],
  "messages": [
    { "from": "client", "to": "auth", "y": 200, "label": "POST /login" },
    { "from": "auth",   "to": "db",   "y": 300, "label": "SELECT user WHERE email=?" }
  ]
}

With "spread" configured, the renderer expands columns to occupy the full viewBox width, preventing unused horizontal space.

Reference Documentation

Key source files in tt-a1i/archify define and document these options:

File	Purpose
archify/schemas/sequence.schema.json	Schema definition for column_fit property and allowed values
archify/SKILL.md (lines 85-86)	Authoring guidance on when to omit or set meta.column_fit
CHANGELOG.md (lines 34-35)	Release notes announcing the column_fit option
archify/renderers/sequence/README.md	Renderer-specific behavior documentation

Summary

• fixed (default): 86 px boxes, 108 px gaps, deterministic geometry, omit column_fit to use
• spread: adaptive spacing to fill viewBox, set "column_fit": "spread" explicitly
• Property location: meta.column_fit inside sequence diagram JSON
• Only "fixed" and "spread" values are valid; no other strings are accepted
• Both modes preserve participant order and message routing semantics

Frequently Asked Questions

What happens if I don't specify column_fit in my sequence diagram?

The renderer automatically applies the fixed layout. As documented in archify/schemas/sequence.schema.json and noted in archify/SKILL.md, omission triggers the stable default behavior with 86 px participant boxes and 108 px inter-column gaps.

Will switching to spread mode change how my messages are routed?

No. The spread option affects only horizontal spacing calculations. Participant order, message from/to routing, and vertical y positioning remain unchanged. The adaptation is purely presentational.

Why would I choose fixed over spread layout?

Use fixed when you need byte-stable output across renders, have compact diagrams that fit within standard widths, or require backward-compatible rendering of existing diagrams. The deterministic geometry makes this mode suitable for version-controlled documentation and automated testing scenarios.

Can I use numeric values or other strings for column_fit?

No. The schema in archify/schemas/sequence.schema.json restricts column_fit to the strings "fixed" and "spread" only. Any other value will fail schema validation and prevent diagram rendering.

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