Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

v2.3.1: audit-driven doc sync, canvas clamp, menu polish, print CSS

tt-a1ib4bb3090be14
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0bb719b7..ef99d824 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,18 @@
All notable changes are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
+## [2.3.1] — 2026-04-15
+
+### Fixed
+- **Stale docs referencing the removed scale selector.** `SKILL.md` frontmatter version bumped `2.0` → `2.3`; the two "2x retina" bullets (lines 18, 233) rewritten to describe the current 4× native pipeline + clipboard copy. `README.md` cleaned up in four places: intro paragraph, "What's new" table (now includes v2.2 column), "Export menu" description (no more "scale selector"), and technical-details section (accurate 4× native-rasterization description, not `Image + 2x canvas`).
+- **Canvas-size clamp for large diagrams.** `rasterize()` now picks the largest integer scale in `{4,3,2,1}` whose `viewBox × scale × scale` fits under a 16 Mpx cap — enough to cover older iOS Safari's silent "blank canvas" ceiling. Default diagrams (viewBox ≈ 1000×680) stay at 4×; only unusually large viewBoxes (say, 1600×1200) step down to 3× automatically.
+- **`?openExport=1` race with font loading.** Replaced the 60 ms `setTimeout(open)` with `document.fonts.ready.then(open)` (+ double `requestAnimationFrame` to let layout settle). Slow connections no longer get a flashed / mispositioned menu on first paint.
+
+### Added
+- **Export menu visual grouping.** Two `<hr role="separator">` dividers split the menu into three sections: *Copy to clipboard*, *Download raster (PNG / JPEG / WebP)*, *Download vector (SVG)*. Makes scanning faster and disambiguates "Copy PNG" vs "Download PNG" at a glance.
+- **Renamed "Copy PNG" → "Copy to clipboard"** with `PNG` moved to the hint badge on the right. The destination ("clipboard") is now in the primary label instead of inferred from context.
+- **Print stylesheet polish.** Added `@page { size: landscape; margin: 1.5cm; }`, expanded container width in print, switched the summary-card grid to two columns in print so the third card doesn't orphan onto a second page, and added `page-break-inside: avoid` for older browsers that don't understand `break-inside`.
+
## [2.3.0] — 2026-04-15
### Fixed
diff --git a/README.md b/README.md
index 763bace0..8a3985e7 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-usin
![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)
![Claude](https://img.shields.io/badge/Claude-Skill-7C3AED?style=flat-square)
-![Version](https://img.shields.io/badge/version-2.3.0-0891b2?style=flat-square)
+![Version](https://img.shields.io/badge/version-2.3.1-0891b2?style=flat-square)
## Preview
@@ -35,19 +35,20 @@ Live example: [`examples/web-app.html`](examples/web-app.html) — open in a bro
## What's new
-Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). 2.0 rewrote the template around a themeable CSS-variable system and added a client-side export pipeline; 2.1 extends that with copy-to-clipboard and selectable export scale:
-
-| Feature | v1.0 | 2.0 | 2.1 | 2.3 |
-|---|---|---|---|---|
-| Dark theme | Yes | Yes | Yes | Yes |
-| Light theme | — | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut |
-| PNG / JPEG / WebP download | manual screenshot | 2× upsampled | 1× / 2× / 4× selector | **4× natively rendered, no blur** |
-| SVG download | — | Vector, styles inlined | Same | Same |
-| Copy PNG to clipboard | — | — | Yes | Yes (always 4×) |
-| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same |
-| Accessibility | — | — | ARIA + focus-visible | Same |
-| Print stylesheet | — | — | — | Yes (from 2.2) |
-| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same |
+Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed a long-standing upsampling bug and made every raster export genuinely sharp at 4× source resolution (the 1× / 2× / 4× selector introduced in 2.1 was removed at the same time — it only encouraged picking a soft-looking scale).
+
+| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 |
+|---|---|---|---|---|---|
+| Dark theme | Yes | Yes | Yes | Yes | Yes |
+| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut |
+| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** |
+| SVG download | — | Vector, styles inlined | Same | Same | Same |
+| Copy PNG to clipboard | — | — | Yes | Same | Yes (always 4×) |
+| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same |
+| Accessibility | — | — | ARIA + focus-visible | Same | Same |
+| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) |
+| Local-font fallback on export | — | — | — | Yes | Yes |
+| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same |
## Quick start
@@ -112,7 +113,7 @@ That's it. Claude generates an HTML file you can open in any browser. Iterate by
Open the generated HTML in any browser. Top-right you'll see two buttons:
- **Theme button** (Dark / Light) — one click flip, persisted across sessions. Shortcut: <kbd>T</kbd>.
-- **Export menu** — opens a dropdown with a scale selector and five actions. Shortcut: <kbd>E</kbd>.
+- **Export menu** — opens a dropdown with five actions (Copy PNG + download PNG / JPEG / WebP / SVG). Shortcut: <kbd>E</kbd>.
### Export menu
@@ -195,7 +196,7 @@ Each color has coordinated dark-mode and light-mode variants that switch togethe
## Technical details
- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.
-- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, current theme variables are resolved and written into a `:root` rule on the clone, then serialized via `XMLSerializer`. For raster formats it's rasterized via an `Image` + 2x `<canvas>` + `toBlob(mime)`. JPEG gets an explicit background fill since it doesn't support transparency.
+- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.
- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~3 KB of embedded JS. No build step, no JS framework, no server.
- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.
diff --git a/archify.zip b/archify.zip
index c40b10dc..4283b1ba 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 32041ad4..b919afde 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -3,7 +3,7 @@ name: archify
description: Create professional architecture diagrams as standalone HTML files with SVG graphics, a built-in dark/light theme toggle, and one-click export to PNG / JPEG / WebP / SVG. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology diagrams, or any technical diagram showing system components and their relationships.
license: MIT
metadata:
- version: "2.0"
+ version: "2.3"
author: tt-a1i
based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
---
@@ -15,7 +15,7 @@ Create professional technical architecture diagrams as self-contained HTML files
Every diagram this skill produces ships with:
- A **Dark / Light theme toggle** (top-right, persists in `localStorage`, respects `prefers-color-scheme` on first visit).
-- An **Export menu** offering **PNG**, **JPEG**, **WebP** (all 2x retina), and **SVG** (vector) — rendered entirely in-browser, no server.
+- An **Export menu** with **Copy PNG to clipboard** plus downloads for **PNG / JPEG / WebP** (all rasterized natively at 4× source resolution for maximum sharpness) and **SVG** (vector, styles inlined) — rendered entirely in-browser, no server.
- A **CSS-variable-driven color system** so both themes remain visually consistent with the same SVG markup.
## The Cardinal Rule: Use CSS Classes, Not Inline Colors
@@ -230,4 +230,4 @@ Produce a single self-contained `.html` file with:
- Inline SVG (no external images)
- Small amount of embedded JS (theme toggle + export) — keep as-is from template
-The file should render correctly when opened directly in any modern browser, and the **Export** menu should cleanly download PNG/JPEG/WebP (2x retina) and a standalone SVG with inlined styles.
+The file should render correctly when opened directly in any modern browser. The **Export** menu should cleanly copy PNG to the clipboard, download PNG / JPEG / WebP (all at 4× source resolution, rendered natively by the browser — no bitmap upsampling), and download a standalone SVG with inlined styles.
diff --git a/archify/assets/template.html b/archify/assets/template.html
index 3ed89951..7ff53539 100644
--- a/archify/assets/template.html
+++ b/archify/assets/template.html
@@ -201,8 +201,12 @@
/* ==========================================================
Print stylesheet — hide interactive controls, force light,
- drop the grid so the diagram doesn't waste ink.
+ drop the grid so the diagram doesn't waste ink, use landscape
+ so wide diagrams fit, pack summary cards into 2 columns to
+ avoid an orphan card on a trailing page.
========================================================== */
+ @page { size: landscape; margin: 1.5cm; }
+
@media print {
:root, [data-theme="dark"], [data-theme="light"] {
--bg: #ffffff;
@@ -215,11 +219,13 @@
--mask: #ffffff;
}
body { background: #ffffff !important; padding: 0; }
+ .container { max-width: none; }
.toolbar, .archify-toast { display: none !important; }
.diagram-container, .card { box-shadow: none; border-color: #e2e8f0; }
+ .cards { grid-template-columns: 1fr 1fr; }
/* Ensure elements break sensibly across pages */
- .card { break-inside: avoid; }
- .diagram-container { break-inside: avoid; }
+ .card { break-inside: avoid; page-break-inside: avoid; }
+ .diagram-container { break-inside: avoid; page-break-inside: avoid; }
h1, .subtitle { color: #0f172a; }
}
@@ -288,6 +294,12 @@
color: var(--text-dim);
font-size: 0.625rem;
}
+ .toolbar .export-menu hr {
+ border: 0;
+ border-top: 1px solid var(--toolbar-border);
+ margin: 0.25rem 0.375rem;
+ opacity: 0.5;
+ }
/* Toast — brief feedback for actions like "copied" */
.archify-toast {
@@ -377,10 +389,12 @@
Export <span aria-hidden="true">&#9662;</span>
</button>
<div class="export-menu" id="export-menu" role="menu" aria-label="Export">
- <button data-action="copy" type="button" role="menuitem" tabindex="-1">Copy PNG <span class="hint">clipboard</span></button>
+ <button data-action="copy" type="button" role="menuitem" tabindex="-1">Copy to clipboard <span class="hint">PNG</span></button>
+ <hr role="separator" aria-hidden="true">
<button data-format="png" type="button" role="menuitem" tabindex="-1">Download PNG</button>
<button data-format="jpeg" type="button" role="menuitem" tabindex="-1">Download JPEG</button>
<button data-format="webp" type="button" role="menuitem" tabindex="-1">Download WebP</button>
+ <hr role="separator" aria-hidden="true">
<button data-format="svg" type="button" role="menuitem" tabindex="-1">Download SVG <span class="hint">vector</span></button>
</div>
</div>
@@ -755,11 +769,29 @@
setTimeout(function () { URL.revokeObjectURL(url); }, 1000);
}
+ // Conservative upper bound on total canvas pixels. Older Safari on iOS
+ // silently produces a blank canvas above ~16 Mpx; Chrome / Firefox /
+ // desktop Safari are far higher but start failing on memory-constrained
+ // devices. We pick the largest integer scale in {4,3,2,1} whose target
+ // pixel count fits under this cap.
+ var MAX_CANVAS_PIXELS = 16 * 1024 * 1024;
+
+ function pickSafeScale(vbW, vbH) {
+ for (var s = RASTER_SCALE; s >= 1; s--) {
+ if (vbW * s * vbH * s <= MAX_CANVAS_PIXELS) return s;
+ }
+ return 1;
+ }
+
function rasterize(format) {
- // Serialize at RASTER_SCALE — the SVG itself will be rasterized by
- // the browser at the target resolution. drawImage then draws at
- // natural size, so no upsampling blur.
- var data = serializeSvg(RASTER_SCALE);
+ // Serialize at a safe scale (RASTER_SCALE=4 by default, reduced if the
+ // resulting canvas would exceed MAX_CANVAS_PIXELS). The SVG itself is
+ // rasterized at target resolution natively; drawImage draws at natural
+ // size — no upsampling blur.
+ var svg = document.querySelector('.diagram-container svg');
+ var vb = svg.viewBox.baseVal;
+ var scale = pickSafeScale(vb.width, vb.height);
+ var data = serializeSvg(scale);
var svgBlob = new Blob([data.svgString], { type: 'image/svg+xml;charset=utf-8' });
var svgUrl = URL.createObjectURL(svgBlob);
@@ -940,9 +972,19 @@
Archify.exportMenu = { open: open, close: close, isOpen: isOpen, run: runExport };
// Auto-open on page load for demo/screenshot purposes: ?openExport=1
+ // Wait for fonts (so the menu doesn't flash before typography lands)
+ // and paint before opening. Fallback timeout for browsers without the
+ // Font Loading API.
try {
if (new URLSearchParams(window.location.search).get('openExport') === '1') {
- setTimeout(open, 60);
+ var openWhenReady = function () {
+ requestAnimationFrame(function () { requestAnimationFrame(open); });
+ };
+ if (document.fonts && document.fonts.ready) {
+ document.fonts.ready.then(openWhenReady);
+ } else {
+ setTimeout(openWhenReady, 200);
+ }
}
} catch (_) {}
})();
diff --git a/examples/images/archify-light.png b/examples/images/archify-light.png
index dd71eacf..dbf8d738 100644
Binary files a/examples/images/archify-light.png and b/examples/images/archify-light.png differ
diff --git a/examples/images/archify-menu.png b/examples/images/archify-menu.png
index b7d99bfe..4c7e691e 100644
Binary files a/examples/images/archify-menu.png and b/examples/images/archify-menu.png differ
diff --git a/examples/web-app.html b/examples/web-app.html
index d5bddead..c565a97f 100644
--- a/examples/web-app.html
+++ b/examples/web-app.html
@@ -201,8 +201,12 @@
/* ==========================================================
Print stylesheet — hide interactive controls, force light,
- drop the grid so the diagram doesn't waste ink.
+ drop the grid so the diagram doesn't waste ink, use landscape
+ so wide diagrams fit, pack summary cards into 2 columns to
+ avoid an orphan card on a trailing page.
========================================================== */
+ @page { size: landscape; margin: 1.5cm; }
+
@media print {
:root, [data-theme="dark"], [data-theme="light"] {
--bg: #ffffff;
@@ -215,11 +219,13 @@
--mask: #ffffff;
}
body { background: #ffffff !important; padding: 0; }
+ .container { max-width: none; }
.toolbar, .archify-toast { display: none !important; }
.diagram-container, .card { box-shadow: none; border-color: #e2e8f0; }
+ .cards { grid-template-columns: 1fr 1fr; }
/* Ensure elements break sensibly across pages */
- .card { break-inside: avoid; }
- .diagram-container { break-inside: avoid; }
+ .card { break-inside: avoid; page-break-inside: avoid; }
+ .diagram-container { break-inside: avoid; page-break-inside: avoid; }
h1, .subtitle { color: #0f172a; }
}
@@ -288,6 +294,12 @@
color: var(--text-dim);
font-size: 0.625rem;
}
+ .toolbar .export-menu hr {
+ border: 0;
+ border-top: 1px solid var(--toolbar-border);
+ margin: 0.25rem 0.375rem;
+ opacity: 0.5;
+ }
/* Toast — brief feedback for actions like "copied" */
.archify-toast {
@@ -377,10 +389,12 @@
Export <span aria-hidden="true">&#9662;</span>
</button>
<div class="export-menu" id="export-menu" role="menu" aria-label="Export">
- <button data-action="copy" type="button" role="menuitem" tabindex="-1">Copy PNG <span class="hint">clipboard</span></button>
+ <button data-action="copy" type="button" role="menuitem" tabindex="-1">Copy to clipboard <span class="hint">PNG</span></button>
+ <hr role="separator" aria-hidden="true">
<button data-format="png" type="button" role="menuitem" tabindex="-1">Download PNG</button>
<button data-format="jpeg" type="button" role="menuitem" tabindex="-1">Download JPEG</button>
<button data-format="webp" type="button" role="menuitem" tabindex="-1">Download WebP</button>
+ <hr role="separator" aria-hidden="true">
<button data-format="svg" type="button" role="menuitem" tabindex="-1">Download SVG <span class="hint">vector</span></button>
</div>
</div>
@@ -590,7 +604,7 @@
<!-- Footer -->
<p class="footer">
- Try <kbd>T</kbd> to toggle theme &middot; <kbd>E</kbd> for Export &middot; raster output is always 4&times; native resolution for maximum sharpness
+ <kbd>T</kbd> toggle theme &middot; <kbd>E</kbd> open Export &middot; <kbd>Cmd</kbd>+<kbd>P</kbd> print &middot; raster output natively rendered at 4&times; source resolution
</p>
</div>
@@ -755,11 +769,29 @@
setTimeout(function () { URL.revokeObjectURL(url); }, 1000);
}
+ // Conservative upper bound on total canvas pixels. Older Safari on iOS
+ // silently produces a blank canvas above ~16 Mpx; Chrome / Firefox /
+ // desktop Safari are far higher but start failing on memory-constrained
+ // devices. We pick the largest integer scale in {4,3,2,1} whose target
+ // pixel count fits under this cap.
+ var MAX_CANVAS_PIXELS = 16 * 1024 * 1024;
+
+ function pickSafeScale(vbW, vbH) {
+ for (var s = RASTER_SCALE; s >= 1; s--) {
+ if (vbW * s * vbH * s <= MAX_CANVAS_PIXELS) return s;
+ }
+ return 1;
+ }
+
function rasterize(format) {
- // Serialize at RASTER_SCALE — the SVG itself will be rasterized by
- // the browser at the target resolution. drawImage then draws at
- // natural size, so no upsampling blur.
- var data = serializeSvg(RASTER_SCALE);
+ // Serialize at a safe scale (RASTER_SCALE=4 by default, reduced if the
+ // resulting canvas would exceed MAX_CANVAS_PIXELS). The SVG itself is
+ // rasterized at target resolution natively; drawImage draws at natural
+ // size — no upsampling blur.
+ var svg = document.querySelector('.diagram-container svg');
+ var vb = svg.viewBox.baseVal;
+ var scale = pickSafeScale(vb.width, vb.height);
+ var data = serializeSvg(scale);
var svgBlob = new Blob([data.svgString], { type: 'image/svg+xml;charset=utf-8' });
var svgUrl = URL.createObjectURL(svgBlob);
@@ -940,9 +972,19 @@
Archify.exportMenu = { open: open, close: close, isOpen: isOpen, run: runExport };
// Auto-open on page load for demo/screenshot purposes: ?openExport=1
+ // Wait for fonts (so the menu doesn't flash before typography lands)
+ // and paint before opening. Fallback timeout for browsers without the
+ // Font Loading API.
try {
if (new URLSearchParams(window.location.search).get('openExport') === '1') {
- setTimeout(open, 60);
+ var openWhenReady = function () {
+ requestAnimationFrame(function () { requestAnimationFrame(open); });
+ };
+ if (document.fonts && document.fonts.ready) {
+ document.fonts.ready.then(openWhenReady);
+ } else {
+ setTimeout(openWhenReady, 200);
+ }
}
} catch (_) {}
})();