How to Configure Grid Layout Mode in Architecture Diagrams with Archify

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 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, 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 (lines 96-108), the base grid definition appears as:

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

To implement this in your diagram:

<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 file. When Archify parses this configuration, it injects the grid-layout class without requiring manual HTML edits.

Create or modify your architecture definition file:

{
  "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 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 (lines 66-115).

To customize a specific section's grid:

<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 — Contains base CSS grid definitions and responsive media queries (lines 96-108, 173-176)
• scripts/gallery-template.html — Defines grid configurations for hero, result, and gallery sections (lines 66-115)
• examples/archify-repo-grid.architecture.json — Example JSON configuration showing the layout property usage
• 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.
• 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 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 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 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 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.

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