How Archify Handles Spacing Math for Diagrams: A CSS‑Based Layout System

Archify uses a deterministic, rem‑based spacing system with CSS flex‑box gaps, letter‑spacing adjustments, and scale‑aware custom properties to guarantee consistent diagram layouts without runtime graph‑layout libraries.

Archify's diagram rendering engine takes a fundamentally different approach to layout than traditional visualization tools. Instead of computing node positions algorithmically at runtime, it delegates all spacing math to the browser's CSS engine through carefully designed static templates. This article examines exactly how spacing math works in the tt-a1i/archify repository, from base units to scale‑aware variables.

Core Spacing Architecture

Archify's layout system rests on three mathematical foundations:

• Rem‑based base unit — All gaps derive from a single spacing unit (typically 0.125rem ≈ 2px)
• Native CSS gap properties — Flex containers handle distribution, not JavaScript
• Typography‑aware letter‑spacing — Text rhythm is mathematically controlled

This architecture appears throughout the template files in scripts/ and governs every diagram produced by the tool.

Base Spacing Unit and CSS Scaling

Every spatial relationship in Archify begins with a base spacing unit defined in rem. When a diagram renders, Archify computes its intrinsic dimensions and injects them into CSS custom properties.

// From generated/maka-regenerated.workflow.json
{
  "diagramWidth": 1385,
  "diagramHeight": 820,
  "spacingUnit": 0.125
}

These values enable proportional scaling. The browser multiplies spacingUnit against rem references throughout the stylesheet, ensuring that a diagram rendered at 1385px wide maintains identical relative gaps to one scaled down for mobile viewports.

Flex‑Box Gap Implementation

Container components in Archify use the native CSS gap property rather than margin hacks. In scripts/start-template.html, the lead‑label bar demonstrates this pattern:

<div class="lead-label">
  <!-- label content -->
</div>

.lead-label {
  display: flex;
  align-items: center;
  gap: .875rem;              /* 7 × base spacing unit */
  margin-bottom: 1.5rem;
  font-family: var(--font-mono);
  font-size: .625rem;
  font-weight: 500;
  letter-spacing: .2em;      /* typographic spacing */
  color: var(--muted);
  text-transform: uppercase;
}

The gap: .875rem equals 7 base units (7 × 0.125rem), creating a consistent 14px gap at standard font sizes.

Letter‑Spacing for Visual Rhythm

Archify treats character spacing as part of the layout math. Negative and positive letter-spacing values tighten or loosen text blocks to align with the overall grid.

In scripts/gallery-template.html, navigation buttons use measured spacing:

.diagram-nav {
  gap: .75rem;               /* 6 × base unit = 12px */
}

.diagram-nav button {
  letter-spacing: .14em;     /* proportional to font-size */
}

Headings receive tighter tracking: letter-spacing: -.028em in the main title panel compresses characters slightly to maintain visual density without sacrificing legibility.

Canvas Padding and Safe Zones

The root diagram container enforces minimum margins through padding, preventing nodes from touching viewport edges. From scripts/gallery-template.html:

<div class="diagram-container">
  <!-- SVG diagram renders here -->
</div>

.diagram-container {
  padding: 1rem;             /* 8 × base unit = 16px margin */
}

This 1rem padding creates a mathematically consistent safe zone around every diagram regardless of content complexity or output format.

Deterministic Layout Guarantees

Because all spacing math lives in static CSS templates, Archify produces identical visual results across:

• Different themes and color presets
• PNG, SVG, and HTML output formats
• Viewport sizes (through CSS scaling variables)

The layout engine does not recalculate positions at runtime. It parses the JSON intermediate representation, injects dimension variables, and lets the browser resolve all spacing according to the predefined rules.

Template Files Controlling Spacing Math

File	Spacing Responsibility
scripts/start-template.html	UI component gaps, label spacing, typographic tracking
scripts/gallery-template.html	Canvas padding, navigation layout, button spacing
generated/*.workflow.json	diagramWidth/diagramHeight values for CSS scaling

The README.md file in the repository root documents this deterministic approach and explains why Archify avoids dynamic graph layout engines.

Summary

• Archify spacing math uses a 0.125rem base unit multiplied throughout CSS templates
• Flex‑box gap properties handle all inter‑element spacing without JavaScript intervention
• Letter‑spacing values are numerically calibrated to the base unit for typographic consistency
• Canvas padding (1rem) guarantees safe margins around every diagram
• Scale‑aware variables (diagramWidth, diagramHeight) enable proportional resizing through CSS custom properties
• Static templates ensure reproducible output across formats and themes

Frequently Asked Questions

Does Archify use a graph layout algorithm like Dagre or ELK?

No. Archify deliberately avoids runtime graph‑layout libraries. All node positioning and edge routing are predetermined by the source workflow structure; spacing between elements is handled exclusively through CSS flex‑box and grid layouts in static templates.

Can I customize the base spacing unit in Archify?

The 0.125rem base unit is hardcoded in the template CSS files. To modify it, you would edit the source in scripts/start-template.html and scripts/gallery-template.html, then regenerate your diagrams. There is currently no configuration parameter for spacing scale.

How does Archify handle responsive diagram sizing?

Archify computes intrinsic dimensions (diagramWidth, diagramHeight) and injects them as CSS custom properties. The browser then scales the diagram proportionally using these variables, maintaining exact relative gaps at any rendered size without recalculating positions.

Why does Archify use letter-spacing instead of just margins?

Letter‑spacing provides sub‑pixel control over text rhythm that margins cannot achieve. By mathematically relating character tracking to the base spacing unit, Archify ensures that text blocks align visually with the surrounding grid even when font sizes vary across diagram components.

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