text2html2png

An agent skill for turning system descriptions, release plans, and technical notes into static visuals. Your agent organizes the content; a local renderer builds the diagram, embeds its fonts, and checks its layout in a browser.

See what you can make

Every example includes Chinese and English fixtures. All example data is synthetic; see asset provenance. Browse the gallery for the source prompts and downloadable outputs.

One paragraph in, a system overview out

Copy this prompt into an agent with the skill installed:

Use text2html2png to create a clean architecture diagram for our README.
Browser → API Gateway → Auth Service and Order Service.
Auth Service uses its own PostgreSQL database. Order Service uses a separate PostgreSQL database and its own Redis.
Do not add cloud providers, protocols, ports, or metrics.
Save the HTML and Diagram JSON, and also export a PNG.

Open the HTML · PNG · Complete Diagram JSON · Chinese example

The architecture layout shows adjacent layers with downward arrows; node descriptions and the footer name the specific dependencies. It is a layered overview, not an arbitrary graph editor. The committed JSON reproduces this example; an agent may organize the same prose differently.

For a longer technical description, see the order events example: three layers and nine nodes retain synchronous requests, asynchronous event routes, three database owners, and delivery boundaries. The source request and complete JSON are public. This is a synthetic design example, not a customer system or performance benchmark.

Quick start

Install the skill:

npx skills add GODVvVZzz/text2html2png -g -y

Then send the prompt above to your agent, or replace the service description with your own material. To target an agent explicitly:

npx skills add GODVvVZzz/text2html2png -g -a codex -y
npx skills add GODVvVZzz/text2html2png -g -a claude-code -y

To revise a diagram, ask your agent to update the JSON and regenerate it. The HTML is a standalone output; the JSON is the reusable source.

Requirements: Node.js 22.12+ to render HTML; a local Chrome, Chromium, Edge, or Brave installation for the required browser layout check and optional PNG export. Before the first render, the agent runs node scripts/setup.mjs --theme clean inside the installed skill directory. This installs the locked runtime and only the selected theme's font packages. Run setup with another theme name when switching themes. It uses your existing browser without downloading another one. The first install needs network access.

Try the renderer without an agent

No installation: open the example gallery to compare source prompts with finished diagrams, switch between Chinese and English, and download HTML, PNG, or complete Diagram JSON. This is a static showcase of prepared examples; it does not send prompts to a model or generate diagrams from new prose.

Edit locally: clone the repository and start the playground. The start command checks and installs the locked runtime and clean-theme fonts:

git clone https://github.com/GODVvVZzz/text2html2png.git
cd text2html2png/skills/text2html2png
npm start

Open the address printed in the terminal. Load one of the nine chart examples, edit its Diagram JSON, preview it, and download HTML or an audited PNG. The playground and renderer need no model API key; natural-language interpretation happens in your agent.

In another terminal, from text2html2png/skills/text2html2png, reproduce the architecture example:

npm run render -- --input ../../docs/examples/service-architecture-en.diagram.json --html architecture.html --audit

For the image too:

npm run render -- --input ../../docs/examples/service-architecture-en.diagram.json --html architecture.html --png architecture.png --force

--png also runs the strict layout audit. --force explicitly replaces an existing output; omit it for new filenames. Use --chrome /path/to/browser or CHROME_PATH if browser discovery needs help.

Supported diagrams

Five themes: clean (default), editorial, notebook, warm, and glass. All 45 chart/theme combinations are supported by the shared rendering contract. The published examples cover a subset; support does not mean every combination has a visual regression baseline.

Why the output is consistent

Your text → Agent → Diagram JSON → Local renderer → HTML → Browser check → Optional PNG

• Reusable source. The same JSON, renderer, and installed dependencies produce the same HTML. PNG pixels also depend on the browser and platform rasterizer.
• Chinese and English fonts. Fonts are installed locally, subset to the characters used, and embedded in the output. Opening a generated diagram does not need a font CDN.
• Measured layout. Browser checks catch clipped, obscured, overlapping, or invisible text; cropped connectors; small type; low contrast; and awkward short-label wrapping, including CJK orphan characters. The agent also inspects the result for meaning and readability.
• Facts stay with the source. The skill instructs the agent to preserve supplied facts and relationships and avoid inventing metrics, dates, people, or infrastructure. Review the result against your input, especially for complex systems.

npm run check:layout rebuilds and audits every published example. Warnings and errors both fail the gate. Findings identify an element, measurements, and a suggested repair; fixes belong in the JSON or shared renderer, followed by another audit.

For the full workflow, read SKILL.md, the Diagram JSON reference, and the rendering contract.

Privacy and boundaries

Rendering runs locally with no project backend, account, or telemetry. Browser audits and PNG export block page network requests and page JavaScript by default, validate the HTML, and keep the Chrome sandbox enabled. Dependency installation uses your npm registry. Your agent's handling of conversation content depends on the agent and model service you choose; local rendering does not change that.

Read PRIVACY.md and SECURITY.md for details. The renderer is intended for generated or explicitly trusted HTML.

Development

skills/text2html2png/
├── SKILL.md       Agent workflow and output contract
├── references/    Chart guides, themes, and rendering rules
├── schemas/       Diagram JSON and configuration schemas
├── examples/      Bilingual source fixtures and generated HTML
├── scripts/       Renderer, local playground, audit, and batch tools
└── tests/         Unit tests and browser checks
docs/             Static gallery and downloadable examples

The standard skills/ layout works with npx skills. The Codex plugin manifest packages the same canonical skill.

From the repository root:

cd skills/text2html2png
npm ci
npm run check

The checks cover skill metadata, theme contracts, example structure, privacy patterns, safe HTML, CLI behavior, browser screenshots, and layout audits. A working browser is required for the full check. Some browser tests skip when no browser can launch; a passing npm test alone is not a full visual check.

For a trusted isolated container that cannot support the browser sandbox, the example builder accepts --no-sandbox: node scripts/build-examples.mjs --audit --no-sandbox.

See CONTRIBUTING.md for contribution checks, acceptance notes, and the theme/chart orthogonality proof for rendering design and development fixtures.

Roadmap

• Richer chart-specific JSON validation and migration tooling
• More dense Chinese/English fixtures across chart and theme combinations
• SVG export
• Community examples with explicit rights and privacy confirmation

License

MIT. See LICENSE.

First-use feedback and evaluation

Run node scripts/setup.mjs --check --theme clean inside the installed skill for read-only environment diagnostics. Setup installs the locked runtime and only the selected theme’s fonts; use another theme name when needed. npm ci still installs all themes for development.

Report your first-use result · Evaluation protocol and 24 fixed tasks. No independent agent success rate or competitive win is claimed.