# How to Configure Grid Layout Mode in Architecture Diagrams with Archify

> Learn to configure grid layout mode in Archify architecture diagrams using CSS classes or JSON settings for responsive design. Easily organize your diagrams.

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

---

**You can configure grid layout mode in Archify architecture diagrams by either adding the `grid-layout` CSS class to the root HTML element or setting `"layout": "grid"` in your [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) configuration file, which applies responsive CSS Grid rules defined in the project's HTML templates.**

Archify is an open-source tool for rendering architecture diagrams as interactive HTML documents. The **grid layout mode** transforms the default flex-based arrangement into a responsive CSS Grid system, giving you precise control over column distribution and responsive behavior across different viewport sizes.

## Understanding Grid Layout Mode

Archify renders architecture diagrams as HTML elements using templates stored in the `scripts/` directory. The grid layout mode leverages CSS Grid to organize diagram nodes into defined columns, automatically collapsing to a single column on mobile devices through media queries.

According to the source code in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html), the grid system uses `minmax()` functions for fluid, responsive columns that adapt to available space while maintaining minimum readable widths.

## Method 1: Enable Grid Layout via CSS Classes

The most direct way to activate grid layout mode is applying the `grid-layout` class to your diagram's root container. This class sets `display: grid` and establishes default column templates.

In [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) (lines 96-108), the base grid definition appears as:

```css
.grid-layout {
  display: grid;
  grid-template-columns: minmax(0, 1.5fr) minmax(260px, 0.65fr);
  gap: 1.5rem;
}

```

To implement this in your diagram:

```html
<div class="diagram-root grid-layout">
  <section class="main-diagram">
    <!-- Primary architecture nodes -->
  </section>
  <aside class="side-panel">
    <!-- Documentation or metadata -->
  </aside>
</div>

```

For responsive adjustments, the template includes media query overrides at lines 173-176 that collapse the grid to a single column on narrow viewports.

## Method 2: Configure Grid Layout in JSON

You can trigger grid layout mode automatically by setting the `layout` property in your [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) file. When Archify parses this configuration, it injects the `grid-layout` class without requiring manual HTML edits.

Create or modify your architecture definition file:

```json
{
  "name": "My Architecture",
  "layout": "grid",
  "nodes": [
    {"id": "frontend", "label": "Frontend Service"},
    {"id": "backend", "label": "Backend API"}
  ],
  "edges": [
    {"from": "frontend", "to": "backend"}
  ]
}

```

The [`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json) file demonstrates this pattern, showing how the `layout` key instructs the renderer to apply grid-specific styling during the HTML generation phase.

## Customizing Grid Templates for Specific Sections

For complex diagrams with multiple distinct areas (hero sections, galleries, or result panels), you can override grid definitions using the templates found in [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) (lines 66-115).

To customize a specific section's grid:

```html
<div class="hero-grid grid-layout">
  <section class="intro">Architecture Overview</section>
  <section class="metrics">System Metrics</section>
  <section class="summary">Executive Summary</section>
</div>

<style>
  .hero-grid {
    grid-template-columns: repeat(3, minmax(0, 1fr));
    gap: 2rem;
  }
</style>

```

This approach uses the **grid-area** definitions already provided by Archify while allowing you to specify custom column distributions using standard CSS Grid syntax.

## Key Source Files Reference

When configuring grid layout mode, these files contain the authoritative implementation:

- **[`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html)** — Contains base CSS grid definitions and responsive media queries (lines 96-108, 173-176)
- **[`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html)** — Defines grid configurations for hero, result, and gallery sections (lines 66-115)
- **[`examples/archify-repo-grid.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo-grid.architecture.json)** — Example JSON configuration showing the `layout` property usage
- **[`examples/maka-architecture.html`](https://github.com/tt-a1i/archify/blob/main/examples/maka-architecture.html)** — Real-world implementation demonstrating grid layout in practice

## Summary

- **Grid layout mode** in Archify converts architecture diagrams from flex layouts to CSS Grid for precise dimensional control.
- **Activate grid mode** by adding the `grid-layout` class to HTML elements or setting `"layout": "grid"` in your JSON configuration.
- **Default templates** use `minmax(0, 1.5fr) minmax(260px, 0.65fr)` for responsive two-column layouts that collapse on mobile.
- **Override templates** by modifying `grid-template-columns` in custom CSS, referencing the base definitions in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html).
- **Responsive behavior** is built-in through media queries that stack grid cells vertically on narrow viewports.

## Frequently Asked Questions

### How do I switch from flex layout to grid layout in an existing Archify diagram?

Change your [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) file to include `"layout": "grid"` at the root level, or manually add `class="grid-layout"` to the root div in your generated HTML. The JSON approach is preferred for maintainability, as the renderer automatically applies the appropriate CSS classes during build time.

### What CSS Grid features does Archify support?

Archify supports standard CSS Grid properties including `grid-template-columns`, `grid-template-rows`, `grid-area`, and `gap`. The templates in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) use `minmax()` functions for fluid columns, and you can extend these with any valid CSS Grid syntax in your custom stylesheets.

### Can I use different grid configurations for different sections of the same diagram?

Yes. The [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/gallery-template.html) file shows implementations of `hero-grid`, `result-grid`, and `gallery-grid` classes that allow different sections to have distinct grid configurations. Apply specific grid classes to section containers and define custom `grid-template-columns` values for each area.

### Where does Archify define the responsive breakpoints for grid layouts?

Responsive breakpoints are defined in [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) at lines 173-176, where media queries override the default two-column grid to a single column layout on narrow viewports. You can modify these breakpoints or add additional media queries to match your specific responsive design requirements.