Skip to content

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

Make Chinese the default README

tt-a1ia8a9089a393b
diff --git a/README.md b/README.md
index 8a3985e7..2f4ee7e5 100644
--- a/README.md
+++ b/README.md
@@ -1,221 +1,237 @@
# Archify
-**Generate beautiful architecture diagrams in chat. Switch dark / light. Copy to clipboard or export crisp 4× PNG / JPEG / WebP / SVG.**
+**聊两句就画出好看的架构图。深色 / 浅色一键切。导出 4× 清晰 PNG / JPEG / WebP / SVG,或直接复制到剪贴板。**
-Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude) that turns a plain-English description of your system into a polished, self-contained architecture diagram — a single HTML file you can open, toggle themes on, copy to the clipboard, and export at maximum resolution.
+Archify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude):你用大白话描述自己的系统,它就把你的描述变成一张做工精细的架构图 —— 一个单文件 HTML,在浏览器里打开就能切主题、复制到剪贴板、导出成各种图片格式。
-- **No design skills needed** — describe your architecture in English, get a diagram
-- **Built-in theme toggle** — one click between dark and light, persists across sessions
-- **Copy PNG to clipboard** — one click, paste straight into Slack / Notion / GitHub
-- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at 4× source resolution (no upsampling blur), or SVG for true vector
-- **Self-contained HTML** — zero dependencies, share by sending the file
-- **Iterate by chat** — "add Redis", "move auth to the left", "use emerald for the API"
+- **不需要会画图** —— 把组件和连接关系说给 Claude 就行
+- **内置主题切换** —— 深色 / 浅色一键切,浏览器记住偏好
+- **一键复制到剪贴板** —— 直接贴到 Slack、飞书、微信、Notion、GitHub issue
+- **导出图片超清晰** —— PNG / JPEG / WebP 全部由浏览器在 4× 源分辨率下**原生光栅化**(不是位图放大,没有糊),或导出 SVG 做真矢量
+- **单文件 HTML** —— 零依赖,发一个文件就能分享
+- **聊天迭代** —— "把 Redis 挪到左边"、"鉴权服务换成玫红"、"加个 Kafka"
![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.1-0891b2?style=flat-square)
-## Preview
+<p align="right"><a href="./README_EN.md">English</a></p>
-Same diagram, two themes, one click to switch:
+## 预览
-| Dark | Light |
+同一张图,两套主题,一键切换:
+
+| 深色 | 浅色 |
|---|---|
-| ![Dark theme](examples/images/archify-dark.png) | ![Light theme](examples/images/archify-light.png) |
+| ![深色主题](examples/images/archify-dark.png) | ![浅色主题](examples/images/archify-light.png) |
-The Export menu — Copy PNG to clipboard plus 4 download formats (all raster exports at 4× source resolution):
+Export 菜单 —— 复制到剪贴板 + 四种格式下载:
-![Export menu](examples/images/archify-menu.png)
+![导出菜单](examples/images/archify-menu.png)
-Print-ready out of the box — <kbd>Cmd</kbd>+<kbd>P</kbd> drops the toolbar, the dark background, and the grid automatically:
+原生支持打印 —— <kbd>Cmd</kbd>+<kbd>P</kbd> 自动隐藏工具栏、换白底、去网格:
-![Print preview](examples/images/archify-print.png)
+![打印预览](examples/images/archify-print.png)
-Live example: [`examples/web-app.html`](examples/web-app.html) — open in a browser, press <kbd>T</kbd> to toggle theme, <kbd>E</kbd> to open Export. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.
+想亲自玩一下:克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html),按 <kbd>T</kbd> 切主题,<kbd>E</kbd> 打开导出菜单。给 URL 加上 `?theme=light` 或 `?openExport=1` 可以强制初始状态。
-## 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** 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).
+Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了一个存在已久的位图升采样 bug,所有光栅导出改为 4× 原生渲染(同时移除了 v2.1 引入的 1×/2×/4× 选择器 —— 那个选择器只是在诱导用户选出更糊的图)。
-| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 |
+| 能力 | 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
-
-### 1. Install the skill
-
-> Requires Claude Pro, Max, Team, or Enterprise plan (or Claude Code).
-
-**Claude.ai:**
-1. Download [`archify.zip`](archify.zip)
-2. Go to **Settings** -> **Capabilities** -> **Skills**
-3. Click **+ Add** and upload the zip file
-4. Toggle the skill on
-
-**Claude Code CLI:**
+| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ |
+| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 |
+| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** |
+| SVG 下载 | — | 矢量 + 内联样式 | 同 | 同 | 同 |
+| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(始终 4×)|
+| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 |
+| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 |
+| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)|
+| 导出时本地字体回退 | — | — | — | ✓ | ✓ |
+| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 |
+
+## 快速上手
+
+### 1. 安装 skill
+
+> 需要 Claude Pro / Max / Team / Enterprise 套餐,或 Claude Code。
+
+**Claude.ai:**
+1. 下载 [`archify.zip`](archify.zip)
+2. 进入 **Settings → Capabilities → Skills**
+3. 点 **+ Add**,上传 zip
+4. 打开开关
+
+**Claude Code CLI:**
```bash
-# Global (all projects)
+# 全局(所有项目可用)
unzip archify.zip -d ~/.claude/skills/
-# Or project-local
+# 或者仅当前项目
unzip archify.zip -d ./.claude/skills/
```
-**Claude.ai Projects (alternative):**
-Upload [`archify.zip`](archify.zip) to your Project Knowledge.
+**Claude.ai Projects:**
+把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。
-### 2. Describe your system
+### 2. 准备系统描述
-Any of these work:
+下面几种都可以:
-**Have AI analyze your codebase:**
+**让 AI 分析你的代码仓库:**
```
-Analyze this codebase and describe the architecture. Include all major
-components, how they connect, what technologies they use, and any cloud
-services or integrations. Format as a list for an architecture diagram.
+分析这个代码仓库,描述系统架构。包括所有主要组件、它们之间怎么连接、
+用了什么技术栈,以及任何云服务或第三方集成。用列表格式,方便画图。
```
-**Write it yourself:**
+**自己写一段:**
```
-- React frontend talking to a Node.js API
-- PostgreSQL database
-- Redis for caching
-- Hosted on AWS with CloudFront CDN
+- React 前端调 Node.js API
+- PostgreSQL 数据库
+- Redis 做缓存
+- 部署在 AWS 上,用 CloudFront 做 CDN
```
-**Or ask for a typical architecture:**
+**或者让 Claude 给个典型架构:**
```
-What's a typical architecture for a SaaS application?
+一个典型的 SaaS 应用架构是什么样的?
```
-### 3. Ask Claude to use the skill
+### 3. 让 Claude 调用 skill
```
-Use your archify skill to create an architecture diagram from this description:
+用 archify skill 帮我生成一张架构图:
-[PASTE YOUR ARCHITECTURE DESCRIPTION HERE]
+[粘贴你上面准备的描述]
```
-That's it. Claude generates an HTML file you can open in any browser. Iterate by chat: "add Redis", "swap Postgres for MySQL", "highlight the auth path".
+完事。Claude 会生成一个 HTML 文件,浏览器打开就能看。想改就接着聊:「加个 Redis」、「把 Postgres 换成 MySQL」、「鉴权那条路径高亮一下」。
-## Using the output
+## 用生成的 HTML
-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 five actions (Copy PNG + download PNG / JPEG / WebP / SVG). Shortcut: <kbd>E</kbd>.
+- **主题按钮**(Dark / Light)—— 一键切换,持久化保存。快捷键 <kbd>T</kbd>。
+- **Export 菜单** —— 五个操作:复制到剪贴板 + 4 种格式下载。快捷键 <kbd>E</kbd>。
-### Export menu
+### Export 菜单
-| Action | What it does |
+| 操作 | 做什么 |
|---|---|
-| **Copy PNG** | Puts a PNG of the current diagram straight on your clipboard. Paste into Slack, Notion, GitHub, Figma. |
-| **Download PNG / JPEG / WebP** | Saves a raster image. JPEG/WebP are painted over the current theme's background (no alpha); PNG keeps transparency. |
-| **Download SVG** | Vector export with all styles inlined. Edit in Figma / Illustrator. Scales losslessly. |
+| **Copy to clipboard** | 当前图以 PNG 格式直接进系统剪贴板,粘贴到 Slack / Notion / 飞书 / GitHub / Figma |
+| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充(无透明);PNG 保留透明度 |
+| **Download SVG** | 矢量导出,所有样式内联。可以在 Figma / Illustrator 里继续编辑。无损缩放 |
+
+所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在 **4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。
-Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **4× the diagram's intrinsic resolution** — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum sharpness is the default and the only option.
+没有倍数选择器 —— 永远最高清晰度,默认也是唯一选项。如果偶尔需要小图,用下面的 URL 参数。
-### Keyboard
+### 键盘快捷键
-- <kbd>T</kbd> anywhere — toggle theme
-- <kbd>E</kbd> anywhere — open the Export menu
-- <kbd>↑</kbd> <kbd>↓</kbd> inside the menu — navigate actions
-- <kbd>Home</kbd> / <kbd>End</kbd> — jump to first / last action
-- <kbd>Enter</kbd> / <kbd>Space</kbd> — activate
-- <kbd>Esc</kbd> — close menu
+- 任何位置按 <kbd>T</kbd> —— 切换主题
+- 任何位置按 <kbd>E</kbd> —— 打开 Export 菜单
+- 菜单里 <kbd>↑</kbd> <kbd>↓</kbd> —— 上下选项
+- <kbd>Home</kbd> / <kbd>End</kbd> —— 跳到第一 / 最后一项
+- <kbd>Enter</kbd> / <kbd>Space</kbd> —— 触发当前项
+- <kbd>Esc</kbd> —— 关闭菜单
-### URL parameters
+### URL 参数
-- `?theme=light` or `?theme=dark` — force a starting theme (deterministic screenshots, share links, embeds)
-- `?openExport=1` — auto-open the Export menu on load (demo / docs screenshots)
+- `?theme=light` 或 `?theme=dark` —— 强制启动主题(确定性截图、分享链接、文档嵌入场景)
+- `?openExport=1` —— 页面加载时自动展开 Export 菜单(演示 / 文档截图)
-### Notes
+### 注意事项
-- **WebP support** depends on your browser's canvas encoder. If unavailable (older Safari), the menu item is dimmed and disabled. PNG and JPEG are universal.
-- **Clipboard support** for images requires `ClipboardItem` + `navigator.clipboard.write` (Chromium, Firefox 127+, Safari 16+). If unavailable, Copy PNG is dimmed.
-- **Fonts in exports**: raster images use the system monospace fallback (`ui-monospace` / Menlo / Consolas) because the sandboxed image-rendering context can't fetch Google Fonts. Install JetBrains Mono locally for pixel-perfect rendering.
+- **WebP 兼容性**:依赖浏览器的 canvas 编码器。老版 Safari 不支持时,菜单项会变灰不可选。PNG 和 JPEG 通用。
+- **剪贴板支持**:图片复制需要 `ClipboardItem` + `navigator.clipboard.write`(Chromium、Firefox 127+、Safari 16+)。不支持时 Copy 选项变灰。
+- **导出字体**:光栅图会使用系统等宽字体回退(`ui-monospace` / Menlo / Consolas),因为沙箱图像渲染上下文拿不到 Google Fonts。本机装了 JetBrains Mono 会自动用上,完全像素级一致。
-## Example prompts
+## 常用 prompt
-**Web app:**
+**Web 应用:**
```
-Create an architecture diagram for a web application with:
-- React frontend
+用 archify 画一张架构图:
+- React 前端
- Node.js/Express API
-- PostgreSQL database
-- Redis cache
-- JWT authentication
+- PostgreSQL 数据库
+- Redis 缓存
+- JWT 鉴权
```
-**AWS serverless:**
+**AWS Serverless:**
```
-Create an architecture diagram showing:
+用 archify 画:
- CloudFront CDN
- API Gateway
-- Lambda functions (Node.js)
+- Lambda(Node.js)
- DynamoDB
-- S3 for static assets
-- Cognito for auth
+- S3 存静态资源
+- Cognito 做鉴权
```
-**Microservices:**
+**微服务:**
```
-Create an architecture diagram for a microservices system with:
-- React web app and mobile clients
+用 archify 画一张微服务架构图:
+- React Web + 移动端
- Kong API Gateway
-- User Service (Go), Order Service (Java), Product Service (Python)
-- PostgreSQL, MongoDB, and Elasticsearch databases
-- Kafka for event streaming
-- Kubernetes orchestration
+- 用户服务(Go)、订单服务(Java)、商品服务(Python)
+- PostgreSQL、MongoDB、Elasticsearch
+- Kafka 做事件流
+- K8s 做编排
```
-## Color palette
+## 语义配色
+
+| 类型 | 颜色 | 用途 |
+|---|---|---|
+| Frontend | 青色 | 客户端 / UI / 终端设备 |
+| Backend | 翠绿 | 服务 / API / 后台进程 |
+| Database | 紫色 | 数据库 / 存储 / AI/ML |
+| Cloud / AWS | 琥珀 | 托管云服务 / 基础设施 |
+| Security | 玫红 | 鉴权 / 安全组 / 加密 |
+| Message Bus | 橙色 | Kafka / RabbitMQ / SNS / 事件总线 |
+| External | 灰色 | 第三方 / 通用外部系统 |
+
+每种颜色在深色 / 浅色主题下都有配套取值,切主题会同步切换。
+
+## 实现细节
+
+- **样式模型**:`:root` + `[data-theme="light"]` 上的 CSS 变量;SVG 元素引用语义 class(`c-frontend`、`t-muted`、`a-emphasis` 等)。切换 `<html>` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。
+- **导出流水线**:克隆 SVG,内联 host `<style>`,解析当前主题变量并写入 clone 的 `:root` 规则,然后用 `XMLSerializer` 序列化。光栅格式下,clone 的 `width`/`height` 被设为 `4 × viewBox`,浏览器按目标分辨率原生光栅化矢量;canvas 尺寸对齐 clone 后按自然大小绘制(无位图升采样),`toBlob(mime)` 生成文件。JPEG 会显式补背景色(无 alpha)。如果目标分辨率超过浏览器 canvas 上限,自动降到 3× 或 2×。
+- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 3 KB 嵌入 JS。无构建步骤、无 JS 框架、无服务端。
+- **浏览器支持**:任何主流浏览器(Chrome、Safari、Firefox、Edge)。WebP 导出需要 canvas 支持 `image/webp`。
-| Component Type | Color | Use for |
-| -------------- | ------- | --------------------------------- |
-| Frontend | Cyan | Client apps, UI, edge devices |
-| Backend | Emerald | Servers, APIs, services |
-| Database | Violet | Databases, storage, AI/ML |
-| Cloud / AWS | Amber | Cloud services, infrastructure |
-| Security | Rose | Auth, security groups, encryption |
-| Message Bus | Orange | Kafka, RabbitMQ, SNS, event buses |
-| External | Slate | Generic, external systems |
+## 致谢
-Each color has coordinated dark-mode and light-mode variants that switch together via the theme toggle.
+Archify 是 [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator)(MIT,v1.0)的 fork 重写,原作者 [Cocoon AI](mailto:[email protected])。原版精致的视觉语言 —— 配色、网格背景、摘要卡片布局、JetBrains Mono 字体 —— 完整保留。视觉设计功劳归属原作者。
-## Technical details
+Archify 2.x 贡献:
-- **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, 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.
+- 模板重构为 CSS 变量主题系统(深色 + 浅色)
+- 主题切换 + `localStorage` 持久化 + `prefers-color-scheme` 默认
+- 内置 PNG / JPEG / WebP / SVG 导出菜单 + 复制到剪贴板
+- 4× 原生光栅化(修复升采样导致的模糊)
+- 键盘导航 + 可访问性语义
+- 打印样式表 + 本地字体回退
+- 更新后的 `SKILL.md` 引导 Claude 使用 class 化、可主题化的画图方式
-## Attribution
+两个项目都是 MIT 协议。
-Archify is a fork / rewrite of [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT, v1.0) by [Cocoon AI](mailto:[email protected]). The original's clean visual design — color palette, grid background, summary-card layout, JetBrains Mono typography — is preserved. All credit for the original aesthetic belongs to them.
+## 路线图
-Archify 2.0 contributes:
-- Refactor of the template to a CSS-variable theme system (dark + light)
-- Theme toggle + `localStorage` persistence + `prefers-color-scheme` default
-- Built-in PNG / JPEG / WebP / SVG export menu
-- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams
+短期和长期计划见 [ROADMAP.md](ROADMAP.md):
-Both projects are MIT-licensed.
+- `?exportScale=N` URL 参数(恢复 1×/2× 轻量出图)
+- 色盲友好调色板(Okabe-Ito)
+- gzip+base64 分享链接
+- `diagram.yaml` 中间格式(撬动 diff / auto-layout / Mermaid 导入 / C4 分层)
## License
-[MIT](LICENSE) — free to use, modify, and distribute.
+[MIT](LICENSE) —— 自由使用、修改、再分发。
-## Contributing
+## 参与贡献
-Issues, PRs, and shared diagrams welcome.
+欢迎 issue、PR、分享你画的图。
diff --git a/README_EN.md b/README_EN.md
new file mode 100644
index 00000000..76404e67
--- /dev/null
+++ b/README_EN.md
@@ -0,0 +1,223 @@
+# Archify
+
+**Generate beautiful architecture diagrams in chat. Switch dark / light. Copy to clipboard or export crisp 4× PNG / JPEG / WebP / SVG.**
+
+Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude) that turns a plain-English description of your system into a polished, self-contained architecture diagram — a single HTML file you can open, toggle themes on, copy to the clipboard, and export at maximum resolution.
+
+- **No design skills needed** — describe your architecture in English, get a diagram
+- **Built-in theme toggle** — one click between dark and light, persists across sessions
+- **Copy PNG to clipboard** — one click, paste straight into Slack / Notion / GitHub
+- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at 4× source resolution (no upsampling blur), or SVG for true vector
+- **Self-contained HTML** — zero dependencies, share by sending the file
+- **Iterate by chat** — "add Redis", "move auth to the left", "use emerald for the API"
+
+![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.1-0891b2?style=flat-square)
+
+<p align="right"><a href="./README.md">中文</a></p>
+
+## Preview
+
+Same diagram, two themes, one click to switch:
+
+| Dark | Light |
+|---|---|
+| ![Dark theme](examples/images/archify-dark.png) | ![Light theme](examples/images/archify-light.png) |
+
+The Export menu — Copy PNG to clipboard plus 4 download formats (all raster exports at 4× source resolution):
+
+![Export menu](examples/images/archify-menu.png)
+
+Print-ready out of the box — <kbd>Cmd</kbd>+<kbd>P</kbd> drops the toolbar, the dark background, and the grid automatically:
+
+![Print preview](examples/images/archify-print.png)
+
+Live example: [`examples/web-app.html`](examples/web-app.html) — open in a browser, press <kbd>T</kbd> to toggle theme, <kbd>E</kbd> to open Export. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.
+
+## 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** 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
+
+### 1. Install the skill
+
+> Requires Claude Pro, Max, Team, or Enterprise plan (or Claude Code).
+
+**Claude.ai:**
+1. Download [`archify.zip`](archify.zip)
+2. Go to **Settings** -> **Capabilities** -> **Skills**
+3. Click **+ Add** and upload the zip file
+4. Toggle the skill on
+
+**Claude Code CLI:**
+```bash
+# Global (all projects)
+unzip archify.zip -d ~/.claude/skills/
+
+# Or project-local
+unzip archify.zip -d ./.claude/skills/
+```
+
+**Claude.ai Projects (alternative):**
+Upload [`archify.zip`](archify.zip) to your Project Knowledge.
+
+### 2. Describe your system
+
+Any of these work:
+
+**Have AI analyze your codebase:**
+```
+Analyze this codebase and describe the architecture. Include all major
+components, how they connect, what technologies they use, and any cloud
+services or integrations. Format as a list for an architecture diagram.
+```
+
+**Write it yourself:**
+```
+- React frontend talking to a Node.js API
+- PostgreSQL database
+- Redis for caching
+- Hosted on AWS with CloudFront CDN
+```
+
+**Or ask for a typical architecture:**
+```
+What's a typical architecture for a SaaS application?
+```
+
+### 3. Ask Claude to use the skill
+
+```
+Use your archify skill to create an architecture diagram from this description:
+
+[PASTE YOUR ARCHITECTURE DESCRIPTION HERE]
+```
+
+That's it. Claude generates an HTML file you can open in any browser. Iterate by chat: "add Redis", "swap Postgres for MySQL", "highlight the auth path".
+
+## Using the output
+
+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 five actions (Copy PNG + download PNG / JPEG / WebP / SVG). Shortcut: <kbd>E</kbd>.
+
+### Export menu
+
+| Action | What it does |
+|---|---|
+| **Copy PNG** | Puts a PNG of the current diagram straight on your clipboard. Paste into Slack, Notion, GitHub, Figma. |
+| **Download PNG / JPEG / WebP** | Saves a raster image. JPEG/WebP are painted over the current theme's background (no alpha); PNG keeps transparency. |
+| **Download SVG** | Vector export with all styles inlined. Edit in Figma / Illustrator. Scales losslessly. |
+
+Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **4× the diagram's intrinsic resolution** — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum sharpness is the default and the only option.
+
+### Keyboard
+
+- <kbd>T</kbd> anywhere — toggle theme
+- <kbd>E</kbd> anywhere — open the Export menu
+- <kbd>↑</kbd> <kbd>↓</kbd> inside the menu — navigate actions
+- <kbd>Home</kbd> / <kbd>End</kbd> — jump to first / last action
+- <kbd>Enter</kbd> / <kbd>Space</kbd> — activate
+- <kbd>Esc</kbd> — close menu
+
+### URL parameters
+
+- `?theme=light` or `?theme=dark` — force a starting theme (deterministic screenshots, share links, embeds)
+- `?openExport=1` — auto-open the Export menu on load (demo / docs screenshots)
+
+### Notes
+
+- **WebP support** depends on your browser's canvas encoder. If unavailable (older Safari), the menu item is dimmed and disabled. PNG and JPEG are universal.
+- **Clipboard support** for images requires `ClipboardItem` + `navigator.clipboard.write` (Chromium, Firefox 127+, Safari 16+). If unavailable, Copy PNG is dimmed.
+- **Fonts in exports**: raster images use the system monospace fallback (`ui-monospace` / Menlo / Consolas) because the sandboxed image-rendering context can't fetch Google Fonts. Install JetBrains Mono locally for pixel-perfect rendering.
+
+## Example prompts
+
+**Web app:**
+```
+Create an architecture diagram for a web application with:
+- React frontend
+- Node.js/Express API
+- PostgreSQL database
+- Redis cache
+- JWT authentication
+```
+
+**AWS serverless:**
+```
+Create an architecture diagram showing:
+- CloudFront CDN
+- API Gateway
+- Lambda functions (Node.js)
+- DynamoDB
+- S3 for static assets
+- Cognito for auth
+```
+
+**Microservices:**
+```
+Create an architecture diagram for a microservices system with:
+- React web app and mobile clients
+- Kong API Gateway
+- User Service (Go), Order Service (Java), Product Service (Python)
+- PostgreSQL, MongoDB, and Elasticsearch databases
+- Kafka for event streaming
+- Kubernetes orchestration
+```
+
+## Color palette
+
+| Component Type | Color | Use for |
+| -------------- | ------- | --------------------------------- |
+| Frontend | Cyan | Client apps, UI, edge devices |
+| Backend | Emerald | Servers, APIs, services |
+| Database | Violet | Databases, storage, AI/ML |
+| Cloud / AWS | Amber | Cloud services, infrastructure |
+| Security | Rose | Auth, security groups, encryption |
+| Message Bus | Orange | Kafka, RabbitMQ, SNS, event buses |
+| External | Slate | Generic, external systems |
+
+Each color has coordinated dark-mode and light-mode variants that switch together via the theme toggle.
+
+## 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, 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.
+
+## Attribution
+
+Archify is a fork / rewrite of [**Cocoon-AI/architecture-diagram-generator**](https://github.com/Cocoon-AI/architecture-diagram-generator) (MIT, v1.0) by [Cocoon AI](mailto:[email protected]). The original's clean visual design — color palette, grid background, summary-card layout, JetBrains Mono typography — is preserved. All credit for the original aesthetic belongs to them.
+
+Archify 2.0 contributes:
+- Refactor of the template to a CSS-variable theme system (dark + light)
+- Theme toggle + `localStorage` persistence + `prefers-color-scheme` default
+- Built-in PNG / JPEG / WebP / SVG export menu
+- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams
+
+Both projects are MIT-licensed.
+
+## License
+
+[MIT](LICENSE) — free to use, modify, and distribute.
+
+## Contributing
+
+Issues, PRs, and shared diagrams welcome.