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

> Archify ensures desktop readability with a 6px text floor and 1440x900 viewport standards. Automatically validate your diagrams with visual-check CLI before publishing.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-09-11

---

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

```javascript
// 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:

```bash
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).