concept-to-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Concept to Image

概念转图片

Creates polished visuals from concepts using HTML/CSS/SVG as a refineable intermediate, then exports to PNG or SVG.

通过HTML/CSS/SVG作为可调整的中间层，将概念转换为精美的可视化内容，随后导出为PNG或SVG格式。

Reference Files

参考文件

File	Purpose
`references/design-guide.md`	Design patterns, anti-patterns, color palettes, typography choices, layout examples
`scripts/render_to_image.py`	Playwright-based export script — takes HTML in, PNG or SVG out
`assets/template.html`	Base HTML template with `.canvas` container and CSS custom properties pre-configured

文件	用途
`references/design-guide.md`	设计模式、反模式、调色板、字体选型、布局示例
`scripts/render_to_image.py`	基于Playwright的导出脚本 —— 输入HTML，输出PNG或SVG
`assets/template.html`	预配置了.canvas容器和CSS自定义属性的基础HTML模板

Why HTML as intermediate

为什么选择HTML作为中间层

HTML is the refineable layer between idea and image. Unlike direct canvas rendering, the user can see the HTML artifact, request changes ("make the title bigger", "swap the colors", "add a third column"), and only export once satisfied. This makes the workflow iterative and controllable.

HTML是想法和图片之间可迭代调整的层。和直接canvas渲染不同，用户可以查看HTML产物，提出修改需求（“把标题调大”、“换个颜色”、“加第三列”），只有满意后才导出，让工作流可迭代、可控。

Workflow

工作流

text

Concept → HTML artifact (view + refine) → PNG or SVG export

Interpret the user's concept — determine what kind of visual best fits (diagram, infographic, card, chart, etc.)
Design a self-contained HTML file using inline CSS and inline SVG — zero external dependencies
Present the HTML as an artifact so the user can preview and request refinements
Iterate on the HTML based on user feedback (colors, layout, content, sizing)
Export to PNG and/or SVG when the user is satisfied, using
```
scripts/render_to_image.py
```

text

Concept → HTML artifact (view + refine) → PNG or SVG export

解读用户的概念 —— 确定最适配的可视化类型（示意图、信息图、卡片、图表等）
设计使用内联CSS和内联SVG的独立HTML文件 —— 无任何外部依赖
展示HTML产物，方便用户预览并提出优化需求
迭代根据用户反馈调整HTML（颜色、布局、内容、尺寸）
导出当用户确认满意后，使用
```
scripts/render_to_image.py
```
导出为PNG和/或SVG格式

Step 1: Interpret the concept

步骤1：解读概念

Determine the best visual format:

User intent	Visual format	Approach
Explain a process/flow	Flowchart or pipeline diagram	SVG paths + boxes
Compare items	Side-by-side or matrix	CSS Grid
Show hierarchy	Tree or layered diagram	Nested containers + SVG connectors
Present data	Chart or infographic	SVG shapes + data labels
Social/marketing graphic	Card or poster	Typography-forward HTML/CSS
Icon, logo, badge	Compact symbol	Pure SVG
Educational concept	Annotated diagram	SVG + positioned labels

确定最优的可视化格式：

用户需求	可视化格式	实现思路
解释流程/链路	流程图或管道示意图	SVG路径+方框
对比不同项目	并列布局或矩阵	CSS Grid
展示层级关系	树形或分层示意图	嵌套容器 + SVG连接线
展示数据	图表或信息图	SVG图形 + 数据标签
社交/营销配图	卡片或海报	突出排版的HTML/CSS
图标、logo、徽章	紧凑型符号	纯SVG实现
教学概念讲解	带标注的示意图	SVG + 定位标签

Step 2: Design the HTML

步骤2：设计HTML

Read

references/design-guide.md

for detailed design patterns and anti-patterns.

Core rules:

Single file, self-contained: All CSS inline in
```
<style>
```
, all graphics as inline
```
<svg>
```
. No external resources.
Fixed viewport: Set explicit
```
width
```
and
```
height
```
on the root container matching the intended export size. This is critical — Playwright screenshots the element at this exact size.
Anti-AI-slop: Avoid centered-everything layouts, purple gradients, uniform rounded corners, and Inter/system font defaults. See design guide for alternatives.
SVG-first for shapes: Use inline SVG for icons, connectors, shapes, and any element that should scale cleanly. CSS for layout and typography.
Color with intention: 3-4 hues max + neutrals. Define as CSS custom properties. Every color encodes meaning.
Start from the template: Use
```
assets/template.html
```
as the base structure.

阅读

references/design-guide.md

了解详细的设计模式和反模式。

核心规则：

单文件、自包含：所有CSS内联在
```
<style>
```
中，所有图形为内联
```
<svg>
```
，无外部资源。
固定视口：给根容器设置明确的
```
width
```
和
```
height
```
，和预期导出尺寸匹配。这一点非常重要 —— Playwright会按这个精确尺寸对元素截图。
避免AI生成劣质效果：不要用所有元素居中的布局、紫色渐变、统一圆角、Inter/系统默认字体，可查看设计指南了解替代方案。
图形优先用SVG：图标、连接线、形状和所有需要无损缩放的元素都使用内联SVG，CSS负责布局和排版。
色彩使用有目的性：最多使用3-4种色相+中性色，定义为CSS自定义属性，每种颜色都对应特定含义。
从模板开始创建：使用
```
assets/template.html
```
作为基础结构。

Sizing guidelines

尺寸规范

Use case	Recommended size
Social media graphic	1200×630
Infographic (portrait)	800×1200
Presentation slide	1920×1080
Square post	1080×1080
Icon/badge	256×256 or 512×512
Wide diagram	1600×900

Set the

.canvas

container to the chosen size. The export script captures this element.

使用场景	推荐尺寸
社交媒体配图	1200×630
竖版信息图	800×1200
演示文稿幻灯片	1920×1080
方形帖子	1080×1080
图标/徽章	256×256 或 512×512
宽幅示意图	1600×900

将

.canvas

容器设置为选定的尺寸，导出脚本会捕获这个元素。

Step 3: Present and iterate

步骤3：展示和迭代

Present the HTML file to the user. They'll see it rendered as an artifact. Common refinement requests:

Color/theme changes → update CSS custom properties
Layout adjustments → modify grid/flexbox
Content changes → edit text/SVG elements
Size changes → update
```
.canvas
```
dimensions

Each iteration is a quick HTML edit, not a full re-render. This is the key advantage over direct image generation.

将HTML文件展示给用户，用户会看到渲染后的产物。常见的优化需求：

颜色/主题修改 → 更新CSS自定义属性
布局调整 → 修改grid/flexbox规则
内容修改 → 编辑文本/SVG元素
尺寸修改 → 更新
```
.canvas
```
的宽高属性

每次迭代只需要快速修改HTML，不需要完全重新生成，这是相比直接图片生成的核心优势。

Step 4: Export to image

步骤4：导出为图片

Once the user is satisfied, run the export script:

bash

python3 scripts/render_to_image.py <input.html> <output.png|.svg> [--width 1200] [--height 630] [--scale 2] [--selector ".canvas"]

当用户确认满意后，运行导出脚本：

bash

python3 scripts/render_to_image.py <input.html> <output.png|.svg> [--width 1200] [--height 630] [--scale 2] [--selector ".canvas"]

Parameters

参数说明

Param	Default	Description
`input`	(required)	Path to HTML file
`output`	(required)	Output path. Extension determines format (.png or .svg)
`--width`	auto	Viewport width (overrides HTML-defined size)
`--height`	auto	Viewport height (overrides HTML-defined size)
`--scale`	2	Device scale factor for PNG (2 = retina quality)
`--selector`	`.canvas`	CSS selector for the element to capture
`--full-page`	false	Capture the full page instead of a specific element

参数	默认值	说明
`input`	（必填）	HTML文件路径
`output`	（必填）	输出路径，扩展名决定格式（.png或.svg）
`--width`	auto	视口宽度（覆盖HTML中定义的尺寸）
`--height`	auto	视口高度（覆盖HTML中定义的尺寸）
`--scale`	2	PNG的设备缩放因子（2 = 视网膜级画质）
`--selector`	`.canvas`	要捕获元素的CSS选择器
`--full-page`	false	捕获完整页面而非特定元素

PNG export

PNG导出

Uses Playwright to launch headless Chromium and screenshot the

.canvas

element at the specified scale factor. Scale 2 produces retina-quality output (e.g., 1200×630 CSS pixels → 2400×1260 PNG).

使用Playwright启动无头模式的Chromium，按指定缩放因子对

.canvas

元素截图。缩放因子为2时可生成视网膜级画质的输出（例如1200×630 CSS像素 → 2400×1260 PNG）。

SVG export

SVG导出

Two strategies, chosen automatically:

SVG-native content: If the
```
.canvas
```
element contains a single root
```
<svg>
```
, extracts it directly as a clean SVG file. This produces a true vector SVG.
HTML-based content: If the content is CSS/HTML-heavy, falls back to PNG export with a note that true SVG requires SVG-native design. The script will warn and suggest redesigning with SVG elements if vector output is needed.

自动选择两种导出策略：

原生SVG内容：如果
```
.canvas
```
元素包含单个根
```
<svg>
```
，直接提取为干净的SVG文件，生成真正的矢量SVG。
基于HTML的内容：如果内容以CSS/HTML为主，回退到PNG导出，并提示真正的SVG需要原生SVG设计。如果需要矢量输出，脚本会发出警告并建议使用SVG元素重新设计。

Delivering the output

交付输出

Present the output file to the user. Always deliver both the HTML (for future editing) and the image (final output).

将输出文件交付给用户，始终同时提供HTML（方便后续编辑）和图片（最终输出）。

Error Handling

错误处理

Error	Cause	Resolution
`playwright` not found	Playwright package not installed	Run `npx playwright install chromium` or `pip install playwright && playwright install chromium`
Browser launch failure	Headless Chromium fails to start	Verify `--headless` mode is supported; check available memory (Chromium needs ~200 MB)
`.canvas` selector not found	HTML does not contain an element matching `.canvas`	Verify `assets/template.html` was used as the base; check the root container has `class="canvas"`
Render timeout	Complex HTML takes too long to render before screenshot	Increase the timeout via `--timeout` flag in the script, or simplify the HTML (reduce DOM depth, inline fewer SVGs)
SVG export falls back to PNG	`.canvas` element contains HTML/CSS content, not a root SVG	See SVG export section; redesign with a single root `<svg>` if vector output is required

错误	原因	解决方案
找不到 `playwright`	未安装Playwright包	运行 `npx playwright install chromium` 或 `pip install playwright && playwright install chromium`
浏览器启动失败	无头模式Chromium启动失败	确认支持 `--headless` 模式；检查可用内存（Chromium需要约200MB内存）
找不到 `.canvas` 选择器	HTML中没有匹配 `.canvas` 的元素	确认使用了 `assets/template.html` 作为基础；检查根容器是否有 `class="canvas"` 属性
渲染超时	复杂HTML在截图前渲染耗时过长	通过脚本的 `--timeout` 参数增加超时时间，或简化HTML（降低DOM深度，减少内联SVG数量）
SVG导出回退到PNG	`.canvas` 元素包含HTML/CSS内容，而非根SVG	查看SVG导出部分的说明；如果需要矢量输出，使用单个根 `<svg>` 重新设计

Limitations

限制

Playwright + Chromium required — the export script cannot run without a working Chromium installation.
macOS and Linux only for headless browser export. Windows Subsystem for Linux works; native Windows Playwright may require separate setup.
SVG export is best-effort — complex HTML/CSS layouts fall back to PNG. True vector SVG requires a single root
```
<svg>
```
as the
```
.canvas
```
child.
Max viewport 4096×4096 — Chromium refuses screenshots larger than this. Use
```
--scale
```
to achieve higher effective resolution within this limit.
No animation support — exported images are static snapshots. CSS animations and JavaScript-driven transitions are frozen at their initial state.

需要安装Playwright + Chromium —— 没有可用的Chromium安装时导出脚本无法运行。
仅支持macOS和Linux 无头浏览器导出，Windows Subsystem for Linux可正常运行；原生Windows的Playwright可能需要单独配置。
SVG导出为尽力而为模式 —— 复杂的HTML/CSS布局会回退到PNG。真正的矢量SVG需要
```
.canvas
```
的子元素为单个根
```
<svg>
```
。
最大视口为4096×4096 —— Chromium不支持更大尺寸的截图，可在该限制内使用
```
--scale
```
获得更高的有效分辨率。
不支持动画 —— 导出的图片为静态快照，CSS动画和JavaScript驱动的过渡效果会冻结在初始状态。

Output Example

输出示例

After a successful export, the script prints the output path and file stats:

text

Exported: concept-diagram.png
  Size:       2400 × 1260 px  (2× scale from 1200 × 630 canvas)
  File size:  ~180 KB
  Format:     PNG (RGBA)

Filename pattern follows whatever was passed as the output argument. Typical file sizes:

Simple diagrams (text + shapes): 80–200 KB
Dense infographics with gradients: 300–600 KB
Full 1920×1080 at 2× scale: 500 KB–1.5 MB

导出成功后，脚本会打印输出路径和文件统计信息：

text

Exported: concept-diagram.png
  Size:       2400 × 1260 px  (2× scale from 1200 × 630 canvas)
  File size:  ~180 KB
  Format:     PNG (RGBA)

文件名遵循输出参数传入的规则，典型文件大小：

简单示意图（文本+形状）：80–200 KB
带渐变的高密度信息图：300–600 KB
2倍缩放的1920×1080全尺寸图：500 KB–1.5 MB

Design anti-patterns to avoid

需要避免的设计反模式

These produce generic "AI-generated" looking output:

Centered everything with equal spacing
Purple/blue gradient backgrounds
Uniform border-radius on all elements
Generic icon libraries (use custom inline SVG)
System font stack without typographic intention
Drop shadows on everything
Low information density (too much whitespace)

这些设计会产生千篇一律的“AI生成”风格输出：

所有元素居中，间距均等
紫色/蓝色渐变背景
所有元素使用统一的border-radius
通用图标库（使用自定义内联SVG）
没有排版考量的系统字体栈
所有元素都加阴影
信息密度低（留白过多）

Font handling

字体处理

Since this environment has limited font access, use web-safe font stacks with intentional fallbacks:

Technical/mono:
```
'Courier New', 'Consolas', monospace
```
Clean sans:
```
'Helvetica Neue', 'Arial', sans-serif
```
Editorial serif:
```
'Georgia', 'Times New Roman', serif
```
Display: Use SVG text with custom paths for display typography when needed

由于当前环境字体访问受限，使用带兜底的网络安全字体栈：

技术/等宽字体：
```
'Courier New', 'Consolas', monospace
```
简洁无衬线字体：
```
'Helvetica Neue', 'Arial', sans-serif
```
排版衬线字体：
```
'Georgia', 'Times New Roman', serif
```
展示字体：需要展示类字体时，使用带自定义路径的SVG文本