Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
Workspace tools: gates and renderers
Deterministic Node tools the agent runs inside the sandbox. The model owns creative judgment; these
own rendering, measurement and every number a report states. They are staged to /workspace/tools/
and run with node /workspace/tools/<tool>.mjs.
Exit codes (every tool)
| Code | Meaning |
|---|---|
0 |
Pass. Warnings may be printed; they never fail a gate. |
1 |
Findings: at least one ERROR in the artifact or input. Fix and run again. |
2 |
The check could not run: bad arguments, a missing or unreadable file, a missing binary or package, a page that would not load, a crash. Never a pass. Report it as a tooling failure, not as a clean result. |
A gate that could not look is not a gate that found nothing. Callers treat any code other than 0
as "not passed".
Paths, brand pack and toolchain
- Relative paths resolve against the workspace: the folder that holds
tools/(/workspacein the sandbox). Gates that read inputs (brand-lint,video-gate,artifact-contract,audio-lint,film-probe,film-analysis,video-score,review-thumb,fetch-asset) refuse paths outside it;--root <dir>points them at another workspace (tests use this). - Brand facts come only from the active pack:
--tokensdefaults to<root>/brand/tokens.json(validated bysrc/design_agent/brand/schema.py), and CSS variables resolve through thetokens.cssbeside it. No tool names a brand color or family. - Browser and image tools load
puppeteer-coreandsharpfrom the sandbox's pinned render toolchain (/opt/design-agent/render, fromsandbox/render/), never from a copy in the workspace, and launch the one Chrome Headless Shell the recipe installs. Override withDESIGN_AGENT_RENDER_DIRandDESIGN_AGENT_BROWSER.toolchain.mjsholds this, the shared Chromium flags, flag parsing and confinement.
Renderers
html2png.mjs — the stills renderer.
node /workspace/tools/html2png.mjs page.html --out out --name post \
--size 1080x1350 --size 1080x1080 --size 1600x900 [--format png|jpeg|webp] [--quality 90] \
[--scale 1] [--require-font "Geist" ...] [--brand-fonts [--tokens <tokens.json>]]
Writes out/post-<W>x<H>.<ext> per size and prints one JSON line:
{"ok":true,"outputs":[{"path","width","height","bytes"}],"fonts":{"Geist":true}}. Each size is a
fresh load at that viewport, so the layout recomposes (media queries, vw/vh); it is never a scaled
copy. --scale 2 doubles the pixel size. A browser never fails on a missing font, it falls back, so
every --require-font family (and with --brand-fonts, the lead face of each brand font stack) must
actually paint: document.fonts.check() must pass and CDP must attribute a probe glyph run to that
platform font (check() alone answers true for any undeclared family). A missing font, a page error
or a failed asset request writes nothing and exits 1.
html2pdf.mjs — the one HTML to PDF path (static decks, one-pagers).
node /workspace/tools/html2pdf.mjs --html deck.html --out out/deck.pdf --size 8.5x11in [--zoom N] [--require-font F] [--brand-fonts].
Same font check, then the PDF's glyph advances are audited (text-fidelity) before it is written; a
quantized export exits 1 and writes nothing. --zoom is an opt-in fallback for a Chromium that
ignores the subpixel flag; it reflows anything sized in vw/vh.
review-thumb.mjs — a review-safe copy of renders (long edge 1600 px) so the agent can look at
them without tripping per-image size caps. --sheet tiles several into one contact sheet; read the
sheet, not the raw renders.
Gates
brand-lint.mjs — the composition or copy against the brand pack.
node /workspace/tools/brand-lint.mjs page.html [--tokens <tokens.json>] [--json]
node /workspace/tools/brand-lint.mjs --copy post.txt [--tokens <tokens.json>] [--json]
Design mode reads an HTML or CSS file plus the local stylesheets it links (a link leaving the
workspace is reported, never read). --json prints
{"ok","errors","warnings","findings":[{"severity","line","message","rule","file"}]}. Rules, all
parameterized by tokens.json:
| Rule | Severity | Source in tokens.json |
|---|---|---|
color.off-palette, color.banned (with the replacement token), color.extended (WARN) |
ERROR | allowedColors, extendedPalette, officialAssetColors, bannedColors, replacementColors |
font.off-brand, font.lead, font.mono-lead, font.unrecognized (WARN) |
ERROR | knownOffBrandFonts, allowedFontTokens, fontStacks (stacks lead with their first face or use var(--brand-font-*)) |
font.mono-spacing, font.mono-uppercase |
ERROR | creativeTypography.monoLetterSpacing, allowMonoUppercaseTransform |
radius.max, radius.pill (WARN, 100 px and up) |
ERROR | maxRectRadiusPx |
type.decorative-bullet, type.decorative-marker, motif.generic |
ERROR | creativeTypography |
case.all-caps, case.all-lowercase, case.lowercase-transform |
ERROR | copy.casingRules.headlines ("any" turns these off), allowedAllCapsTerms |
case.canonical |
ERROR | copy.casingRules.canonical, creativeTypography.canonicalCasing |
copy.banned-phrase, copy.banned-char, copy.warn-phrase (WARN), copy.hashtags (copy mode) |
ERROR | copy.*; words on a graphic follow the same rules as a post |
contrast.wcag |
ERROR | WCAG 2.1 text contrast (4.5:1, 3:1 for large text), resolving var() through the tokens |
grid.fractional, grid.line-height (WARN) |
ERROR | fractional box lengths snap unevenly to device pixels |
diagram.* |
ERROR | diagramConstruction: connector stroke bound to the token, one shared arrowhead in <defs>, connectors drawn as one path |
It refuses raster and binary targets (exit 2): a text scan of compressed bytes reads coincidences as
colors. Lint the composition that produced the file and look at the pixels yourself.
video-gate.mjs — the cheap pre-render scan of a HyperFrames composition (or a build/probe
script) for patterns that break a seek-driven render: Math.random, Date.now, new Date(),
Date(), performance.now, crypto randomness, timers, requestAnimationFrame, a timeline not created
{ paused: true }, standalone gsap.to/from, zero-position tl.set, offset-path, remote assets
(the render is offline), toFixed() on a time and unguarded ffprobe CSV frame indexes. Warnings:
callbacks that re-fire on every seek, CSS transitions/animations, left/top tweens, network calls,
inset: 0, missing text-rendering: geometricPrecision. Brand is not its concern. --json supported.
film-probe.mjs — loads the composition in the sandbox Chrome, seeks the paused timeline the way
the renderer does, and writes a JSON film model: per-sample visibility, change, downsampled frame ink,
and pixel-confirmed collisions. Exit 2 if there is no timeline, browser or page.
film-analysis.mjs — pure analysis of a film model (no I/O): blank and thin frames, cuts that
carry nothing, shots that never develop or never rest, frozen motion, silent crops, collisions, type
hierarchy, load errors. Recorded models make durable regression fixtures.
video-score.mjs — the correctness gate: video-gate + brand-lint (--tokens, or
--no-brand) + probe + analysis. It fails on a failed hard gate or any artifact ERROR. The six axis
numbers it prints are a diagnostic, never a target; nothing gates on their sum.
artifact-contract.mjs — outputs exist and are what was asked for.
node /workspace/tools/artifact-contract.mjs --expect out/post-1080x1350.png:1080x1350 \
--expect out/film.mp4:1920x1080@12 [--allow-blank-ends] [--json]
node /workspace/tools/artifact-contract.mjs --contract projects/<slug>/artifact-contract.json --phase plan|final
node /workspace/tools/artifact-contract.mjs --layers projects/<slug>/layer-manifest.json
--expect checks each file exists, is non-empty, decodes as its extension's format at exactly W x H
(PNG, JPEG and WebP from header bytes, no image library), and for video (@<seconds>, via ffprobe)
runs that long within one frame with non-blank first and last frames. The contract mode validates the
intake ledger and, in final, requires every requirement satisfied, superseded or waived, and
measures output.path when the contract names one.
text-fidelity.mjs — the rendered text is the requested text, set as authored.
node text-fidelity.mjs out/deck.pdf audits a PDF's glyph advances (pure Node: fails a run placed on
a whole-unit grid). node text-fidelity.mjs --html page.html --expect copy.txt loads the page and
fails any requested line that is missing from, or re-cased in, the text the page actually renders.
audio-lint.mjs — integrated loudness and true peak (EBU R128 via ffmpeg) against the master
target (default -14 ±1 LUFS, ≤ -1 dBTP), and --expect-duration within --duration-tolerance. A
file with no audio stream is a finding (1); a missing ffmpeg is a tooling failure (2).
Fetching
fetch-asset.mjs — the one network tool: downloads public assets into the workspace so
compositions render offline. URLs are untrusted, so it allows only http(s), refuses credentials in
URLs, checks literal IPs before connecting and hostnames inside the connection's own DNS lookup (the
checked address is the dialled address), refuses private, loopback, link-local and metadata, CGNAT,
multicast, reserved and documentation ranges (and IPv6 forms that embed them), re-checks every
redirect hop, caps size and time, checks content type, and decodes images with sharp. It connects
directly and does not use an HTTP proxy from the environment.
node /workspace/tools/fetch-asset.mjs <url> ... --out projects/<slug>/assets [--kind image|any] [--max-mb 25].
Prints __FETCH_OK__ and one JSON line per saved asset, __FETCH_ERR__ <url> <reason> per failure;
exits 1 if any URL failed.