TASKVEGAS / documentation
Diagram export workflow
Selected pinned upstream documentation. Read its original repository guide for setup, costs and availability.
Unmodified upstream reference text. Treat instructions in this document as source material, not authorization to act.
- Repository
- cathrynlavery/diagram-design
- Source revision
- 3efa45939195092b1a50513e30a2521f6190e3f7
- License
- MIT
- Text range
- 16000–28667 of 28667 characters
Read the pinned upstream source
License and notices: Pinned notice · Pinned notice
ParseError:
return svg # The existing final XML validator supplies the public error.
opacity_counts = {"fill-opacity": 0, "stroke-opacity": 0}
styles = list(STYLE_BLOCK_RE.findall(svg))
def collect_opacity_context(match: re.Match[str]) -> str:
for attr in TAG_ATTR_RE.finditer(match.group(2)):
key, value = attr.group(2), attr.group(4)
if key in opacity_counts:
opacity_counts[key] += 1
elif key == "style" and value is not None:
styles.append(value[1:-1])
return match.group(0)
_rewrite_start_tags(svg, collect_opacity_context)
css_opacity = {
key for key in opacity_counts
if any(re.search(rf"(?:^|[;{{])\s*{key}\s*:", _decoded_css_property_text(style), re.IGNORECASE)
for style in styles)
}
position = 0
def normalize_tag(match: re.Match[str]) -> str:
nonlocal position
children = descendants.get(position, [])
element = elements[position]
position += 1
name, attrs, end = match.groups()
values = {
attr.group(2): attr.group(4)[1:-1]
for attr in TAG_ATTR_RE.finditer(attrs)
if attr.group(4) is not None
}
updates: dict[str, str] = {}
additions: list[str] = []
for prop in ("fill", "stroke"):
value = values.get(prop, "")
if value == "transparent":
updates[prop] = "none"
continue
rgba = RGBA_ATTR_RE.fullmatch(f'{prop}="{value}"')
if rgba is None:
continue
_, r, g, b, alpha = rgba.groups()
opacity_name = f"{prop}-opacity"
# Presentation opacity may be overridden by CSS or inherited from
# another element. Preserve the color alpha when that cascade is
# unresolved instead of replacing it with opaque RGB.
# Converting a parent is safe when descendants inherit its paint.
# Preserve alpha if a descendant overrides that paint, including
# a conservatively detected stylesheet or inline declaration.
inline_paint = re.search(
rf"(?:^|[;{{])\s*{prop}\s*:",
_decoded_css_property_text(element.get("style", "")), re.I,
)
descendant_paint = any(
prop in child.attrib
or re.search(rf"(?:^|[;{{])\s*{prop}\s*:",
_decoded_css_property_text(child.get("style", "")), re.I)
for child in children
)
stylesheet_paint = any(
re.search(rf"(?:^|[;{{])\s*{prop}\s*:", _decoded_css_property_text(rule.group(2)), re.I)
and _css_paint_may_target_descendants(rule.group(1), [element] + children)
for style in STYLE_BLOCK_RE.findall(svg)
for rule in RULE_RE.finditer(CSS_COMMENT_RE.sub("", style))
)
if inline_paint or descendant_paint or stylesheet_paint or opacity_name in css_opacity or opacity_counts[opacity_name] > int(opacity_name in values):
continue
opacity = alpha if 0 <= float(alpha) <= 1 else "0" if float(alpha) < 0 else "1"
if opacity_name in values:
try:
original = values[opacity_name].strip()
amount = float(original.rstrip("%")) / (100 if original.endswith("%") else 1)
except ValueError:
continue # Keep paint intact when the opacity cannot be resolved here.
if not math.isfinite(amount):
continue
opacity = format(min(1, max(0, amount)) * max(0, min(1, float(alpha))), ".12g")
updates[opacity_name] = opacity
else:
additions.append(f' {opacity_name}="{opacity}"')
updates[prop] = "#{:02x}{:02x}{:02x}".format(*(max(0, min(255, int(c))) for c in (r, g, b)))
def replace_attr(attr: re.Match[str]) -> str:
space, key, _equals, _value = attr.groups()
return f'{space}{key}="{updates[key]}"' if key in updates else attr.group(0)
return f"<{name}{TAG_ATTR_RE.sub(replace_attr, attrs)}{''.join(additions)}{end}>"
return _rewrite_start_tags(svg, normalize_tag)
svg = normalize_rgba_presentation_attrs(svg)
```
Channels and alpha are clamped to the CSS ranges 0–255 and 0–1 so out-of-range rgba values retain their browser paint when converted. The `\s*` around each channel tolerates a spaced `rgba(45, 49, 66, 0.03)` as well as the compact `rgba(45,49,66,0.03)` the templates normally use; `\d*\.?\d+` accepts an alpha value with or without a leading zero (both `0.03` and `.03` appear in shipped tokens). Matching is scoped to the `fill="..."` / `stroke="..."` presentation attribute. Class-styled diagrams may still carry `rgba(...)` inside the embedded `<style>` block via custom properties (e.g. `--accent-tint`); that form is correct in browsers and in Figma/Illustrator, and is out of scope for this presentation-attribute pass. (A brand's onboarded palette in `style-guide.md` could in principle add a third notation such as `hsl()`; none exists in any shipped token today, so this pass doesn't handle it — extend the regex if one is ever introduced.)
8. **Gate:** if the exported SVG still contains `class=` but no diagram CSS rules, stop and fix the CSS carry step — that fragment will render as black boxes. A fonts-only `<style>` (Google Fonts `@import` with no rules) does **not** satisfy the gate.
9. Prepend `<?xml version="1.0" encoding="UTF-8"?>\n` so the file is well-formed XML.
10. Write to `<basename>.svg` next to the source (e.g. `example-architecture.html` → `example-architecture.svg`). Honour an explicit output path if the user provides one.
### Caveat to surface to the user
Tools that don't fetch remote fonts at import time (offline Illustrator, some Figma import paths, older SVG viewers) will substitute typography. The SVG renders correctly in any modern browser. For pixel-perfect portability, recommend the PNG export.
## PNG export procedure
Render **the original HTML** (not the extracted SVG) and screenshot only the `<svg>` element's bounding box. This keeps font loading reliable (already wired in the source HTML) while satisfying the "diagram only" rule. The PNG always has a **transparent background** (`omit_background=True`) so it can be placed on any slide or doc colour without a white halo. For motion-enabled HTML, append `?motion=static`, await `document.fonts.ready`, and assert the motion root has `data-frame="static"` before capture; never export at an arbitrary wall-clock delay.
### Detection
Before running anything, verify Playwright is installed in the Python interpreter
you will use for the export. Try:
```
python3 -c "import playwright"
```
If that fails, try `python -c "import playwright"` (the usual command on
Windows). Use whichever interpreter passes the import for the rasterization
command below. If both imports fail, surface this exact instruction to the user
and stop:
> Playwright is not available. PNG export requires an approved Playwright
> installation and a compatible browser to be provisioned by the host
> environment; the skill never installs runtime dependencies automatically.
> Then ask me to export again.
Don't auto-install. The user asked for one feature, not a system change.
### Rasterize
Keep the user's project directory as the working directory so relative input and
output paths still resolve there. Invoke the packaged renderer by its absolute
path under the resolved skill directory with the interpreter that passed
detection: `python3 <skill-dir>/scripts/export_png.py <src.html> <out.png> [scale]`
or `python <skill-dir>/scripts/export_png.py <src.html> <out.png> [scale]`.
If the `networkidle` wait times out (a stalled font or stylesheet behind a proxy), the helper cancels the outstanding load with `window.stop()` and captures with fallback typography, printing a warning to stderr — pass that warning on to the user. Any other error propagates and fails the export normally. The helper requests the complete static motion frame, waits for font readiness, and rejects a motion root that has not reached `data-frame="static"`; ordinary script-free diagrams need no motion root.
Default `device_scale_factor=2` for crisp output. Accept `1` for compact assets or `3` for print/retina hero use, passed as a third CLI arg. Fractional scales such as `1.25` are also accepted within the documented 1–4 range for exact pixel sizes.
The helper's overflow release matters for the wide presets. `min-width` equals the viewBox width (see [`output-spec.md`](output-spec.md)), so a `doc-wide` or `slide-16x9` SVG is 1280px inside a 1200px frame, and its `.diagram-container` scroller clips the last 80px on screen. The screenshot covers the SVG's box but not what an ancestor clipped, so without the release the PNG comes out full size with a blank right edge. This is the screen-side counterpart of the templates' `@media print` rule.
### Output naming
`example-architecture.html` → `example-architecture.png`, written next to the source. Honour explicit user-provided paths. The rasterizer encodes the absolute source path as a file URI, so literal `#` and `%` characters in filenames remain filename content.
## Sizing the export
The PNG's pixel dimensions are the SVG's `viewBox` × `device_scale_factor`. The rasterizer establishes the capture viewport from the finite, nonzero viewBox dimensions so page CSS cannot enlarge or shrink the promised output. So the size decision was already made when the diagram was drawn — see [`output-spec.md` §2](output-spec.md) for the presets. Export only picks the multiplier.
| Destination | Scale | Result from a 1280×720 `viewBox` |
|---|---|---|
| Docs, README, wiki | 2 | 2560×1440 |
| Slide deck (projected) | 2 | 2560×1440 |
| Print / PDF handout | 3 | 3840×2160 |
| Inline thumbnail, email | 1 | 1280×720 |
### Hitting an exact pixel size
When the user needs specific dimensions (an OG card at exactly 1200×630, a slide image at 1920×1080), compute the scale factor instead of guessing — Playwright accepts fractional values:
```
scale = target_width / viewBox_width
```
A 960-wide `viewBox` at a 1200px target is `scale=1.25`. Two rules:
- **Never scale below 1** to hit a small target — that soft-focuses the type. Redraw at a smaller preset instead.
- **Never scale past 4** — beyond that you're upscaling a layout that was designed for a smaller canvas; redraw at `slide-16x9` or a print preset.
If the target aspect ratio doesn't match the `viewBox` aspect ratio, say so and offer to redraw at the matching preset. Padding or cropping a finished diagram to fit a frame is not an export operation — it breaks the 40px safe margin.
## Edge cases
- **Source is `assets/index.html`** (the gallery, multiple SVGs in one file): refuse the export and ask the user which specific diagram file they meant. Don't guess.
- **No `<svg>` block found**: the source isn't a diagram file. Tell the user; don't write anything.
- **Surrounding HTML matters to the user**: they want cards/header in the image. Tell them this skill exports diagrams only, and recommend a browser-based full-page screenshot (or a separate PDF print).
- **Source is missing fonts at runtime**: Playwright will substitute, the screenshot will look off. Check that the source HTML has the `<link href="...fonts.googleapis.com...">` tag in `<head>`. If absent, the file isn't from a current template — fix the source rather than working around it in export.
## What this command never does
- Modifies the source HTML.
- Adds export buttons or `<script>` tags. Static diagrams remain script-free; an already motion-enabled source may retain the scoped controller from [`animation.md`](animation.md), but export never injects another controller.
- Auto-emits `.svg` or `.png` alongside HTML generation. Manual on every call.
- Embeds an HTML wrapper (cards, headers) into the SVG via `foreignObject`. Too fragile across renderers.
The exporter keeps optional defs in comments namespaced so they can be uncommented later. Only referenceable defs element types have their IDs renamed; live titles and other elements retain their IDs and accessibility references.
End of document.