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

> Discover how Archify uses CSS for spacing math to create consistent diagram layouts. Learn about its rem-based system, flex-box gaps, and scale-aware properties for reliable visuals.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-02

---

**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.

```json
// 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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), the lead‑label bar demonstrates this pattern:

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

```

```css
.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`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html), navigation buttons use measured spacing:

```css
.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`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html):

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

```

```css
.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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | UI component gaps, label spacing, typographic tracking |
| [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) and [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/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.