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`	基础HTML模板，预配置了 `.canvas` 容器和CSS自定义属性

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是连接想法与图片的可优化层。与直接画布渲染不同，用户可以查看HTML产物，请求修改（"把标题调大"、"更换颜色"、"添加第三列"），直到满意后再导出。这让工作流程具备迭代性和可控性。

Workflow

工作流程

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
```

概念 → HTML产物（查看+优化）→ PNG或SVG导出

解读用户的概念 — 确定最适合的可视化类型（图表、信息图、卡片、统计图等）
设计一个自包含的HTML文件，使用内联CSS和内联SVG — 无外部依赖
呈现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`	自动	视口宽度（覆盖HTML中定义的尺寸）
`--height`	自动	视口高度（覆盖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元素重新设计。

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>` 作为 `.canvas` 的子元素

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子系统Linux（WSL）可正常工作；原生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:

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

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

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
1920×1080分辨率2倍缩放：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生成"风格输出：

全居中布局且间距均等
紫色/蓝色渐变背景
所有元素使用统一圆角
通用图标库（使用自定义内联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

由于此环境的字体访问受限，使用带有明确备选方案的Web安全字体栈：

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