Desktop Readability Constraints in Archify: Viewport Standards and Text Floor Validation

Archify enforces strict desktop readability constraints that require all node labels to project to at least 6 px when viewed on a 1440×900 px viewport, automatically validating diagrams through the visual-check CLI before publication.

The tt-a1i/archify repository implements a comprehensive readability budget to ensure architecture diagrams remain legible on standard desktop displays. These desktop readability constraints are defined in the core rendering utilities and applied during the visual-check phase, preventing the publication of diagrams that would render unreadable text at typical monitor resolutions.

Viewport and Canvas Dimensions

Archify establishes a baseline reference environment that simulates how diagrams appear on actual desktop screens.

Reference Viewport Size

The system treats 1440 × 900 px as the canonical desktop window for all readability calculations. This constant is exported as DESKTOP_READABILITY_VIEWPORT from the shared rendering utilities.

Usable Diagram Width

While the reference viewport is 1440 px wide, Archify assumes a minimum diagram width of 960 px for the desktop reader. After subtracting a horizontal chrome gutter of 30 px (defined as DESKTOP_READER_HORIZONTAL_CHROME), the usable diagram width becomes 930 px. These constraints ensure that diagrams retain adequate padding and border space while maintaining legibility.

The 6-Pixel Projected Text Floor

The cornerstone of Archify’s readability system is the projected-text floor, which prevents microscopically small labels.

Minimum Acceptable Text Size

Any node label that projects to smaller than 6 px is considered unreadable, as defined by the MIN_PROJECTED_NODE_TEXT_PX constant in archify/renderers/shared/desktop-readability.mjs. If the projectedNodeTextPx() function determines a label would render below this floor, the diagram immediately fails validation.

Computing Projected Text Size

The projection calculation accounts for the relationship between the source SVG viewBox and the final rendered size. The function projectedNodeTextPx(sourceFontPx, viewBoxWidth, diagramWidth) accepts the original font size and diagram dimensions, returning the actual pixel size that text would occupy on the 1440×900 reference display.

Calculating Minimum Readable Font Sizes

When diagrams fail the readability check, Archify provides actionable guidance through inverse calculations.

The minimumReadableSourceTextPx(viewBoxWidth, diagramWidth, minimumProjectedPx) function determines the smallest source font size that will still meet the 6 px floor for a given viewBox. This value drives automated suggestions to widen the viewBox, reduce label length, or increase font sizes before re-running the visual check.

Validation Flow and Error Reporting

Readability validation occurs during the visual-check execution, with comprehensive diagnostics for failed assertions.

Visual Check Implementation

In archify/bin/visual-check.mjs (lines 508–793), Archify collects readability observations for each viewport. The overall status returns "pass" only if all viewports meet the projected-text floor; otherwise, the status is "fail" and the system emits a detailed diagnostic entry with the code viewer/projected-text-readability.

Diagnostic Messages

When validation fails, Archify generates specific error messages indicating which nodes violate the constraints. The system reports: “Projected <node> text is below the readability floor at <width>×<height>.” This appears in the diagnostic output between lines 640–648 of the visual-check implementation.

CLI Remediation Guidance

The archify.mjs CLI entry point maps the composition/desktop-readability error code to user-friendly remediation strategies (lines 231–232). When diagrams fail readability checks, the CLI suggests four primary fixes:

• Reduce the viewBox width to increase relative text size
• Shorten node copy to decrease text density
• Widen affected nodes to provide more rendering space
• Split the diagram into smaller components so that node context remains ≥ 6 px at the 1440×900 viewport

Implementing Readability Checks in Code

Developers can programmatically verify diagrams against Archify’s constraints using the exported utilities:

// Verify that a diagram meets Archify’s desktop readability constraints
import {
  DESKTOP_READABILITY_VIEWPORT,
  DESKTOP_READER_MIN_WIDTH,
  MIN_PROJECTED_NODE_TEXT_PX,
  projectedNodeTextPx,
  minimumReadableSourceTextPx,
} from './archify/renderers/shared/desktop-readability.mjs';

// Assume a diagram with a viewBox width of 800 px and a node label of 10 px source font
const viewBoxWidth = 800;
const sourceFontPx = 10;

// Compute projected pixel size for the desktop viewport
const projectedPx = projectedNodeTextPx(
  sourceFontPx,
  viewBoxWidth,
  /* diagramWidth = */ DESKTOP_READER_MIN_WIDTH - 30
);

if (projectedPx < MIN_PROJECTED_NODE_TEXT_PX) {
  console.warn(
    `Projected node text (${projectedPx.toFixed(2)} px) is below the readability floor.`
  );

  // Suggest the minimum source font that would satisfy the floor
  const minSourceFont = minimumReadableSourceTextPx(
    viewBoxWidth,
    DESKTOP_READER_MIN_WIDTH - 30,
    MIN_PROJECTED_NODE_TEXT_PX
  );
  console.info(`Increase source font to ≥ ${minSourceFont.toFixed(2)} px or widen the viewBox.`);
}

To validate an entire diagram file through the command line:

npx archify visual-check path/to/diagram.architecture.json

Summary

• Archify uses a 1440×900 px reference viewport (DESKTOP_READABILITY_VIEWPORT) as the baseline for all desktop readability checks.
• Diagrams must maintain a minimum projected text size of 6 px (MIN_PROJECTED_NODE_TEXT_PX) to pass validation.
• The usable diagram width is 930 px, accounting for a 30 px horizontal chrome gutter.
• The projectedNodeTextPx() function calculates actual rendered text sizes, while minimumReadableSourceTextPx() suggests corrective font adjustments.
• Failed readability checks trigger the composition/desktop-readability error code with specific diagnostic messages generated in archify/bin/visual-check.mjs.

Frequently Asked Questions

What is the minimum projected text size Archify accepts?

Archify enforces a hard floor of 6 px for any projected node text. If the projectedNodeTextPx() calculation returns a value below this threshold for the 1440×900 reference viewport, the diagram fails validation and cannot be published until corrected.

How does Archify calculate projected text size for node labels?

The projectedNodeTextPx(sourceFontPx, viewBoxWidth, diagramWidth) function in archify/renderers/shared/desktop-readability.mjs computes the final rendered pixel size by comparing the source font size against the diagram’s viewBox width and the usable canvas width. This projection simulates how the SVG text scales when displayed on the reference desktop viewport.

What happens if my diagram fails the desktop readability check?

When validation fails, the visual-check CLI returns a "fail" status and emits a diagnostic entry with the code viewer/projected-text-readability. The error message specifically identifies which nodes fall below the 6 px floor and at which viewport dimensions the violation occurs, as implemented in lines 640–648 of archify/bin/visual-check.mjs.

How can I fix diagrams that violate the 6-pixel text floor?

The Archify CLI provides four remediation strategies: reduce the viewBox width to increase text scaling, shorten node labels to decrease density, widen individual nodes to provide more rendering space, or split complex diagrams into smaller components. These suggestions map to the composition/desktop-readability error code in archify/bin/archify.mjs (lines 231–232).

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