Artifact
Rules for producing, checking and opening PDFs, HTML reports, slides and formulas. Check every artifact visually before showing it: text visible and legible, consistent, inside its borders.
Visual design check
Before showing a diagram, chart, slide or report: the primary takeaway is apparent at a glance to its audience; every accent colour carries information; every size or colour difference means something; elements sit on one grid and text aligns to its reading direction (right for Persian); steps and containers have room to breathe.
PDFs
- For a scanned PDF: run
pdfinfo, then onepdftotext -layoutcheck; if it is empty, render pages withpdftoppmtotmp/pdfs/and inspect the PNGs at original detail. - Keep a short inventory: page count, text-extraction result and what the pages contain.
- Stay local; use no online OCR or upload unless the user asks.
- After creating or editing a PDF the user will inspect, render a page to check it, then open it for the user with the environment's opener and confirm the viewer started.
HTML reports
- After creating or materially editing a user-facing HTML artifact, open it for the user unless they say not to. A screenshot or headless render verifies it; it does not replace opening it.
- Open HTML in Chromium. For a site folder, especially one with assets, scripts or maps, serve it locally:
setsid python3 -m http.server <port> --directory <site-dir> >/tmp/<task>-server.log 2>&1 &, then openhttp://127.0.0.1:<port>/.... Usefile://only for a simple standalone page; if Chromium keeps loading, switch to the local server before saying it is open. - Browser automation and screenshots are costly. Use cheaper local checks unless the UI, formulas or charts are new or materially changed; then do one visual pass before opening.
- Make alternative designs switchable in the HTML rather than describing them in chat.
Slides and print layout
- For browser-printed HTML slides, do not rely on
.activestyles: print mode often forces every.slidetodisplay:flex, so putflex-direction,justify-contentandgapon the base.slideclass. - Check layout by rendering the PDF pages, not by reading extracted text: spot-check the most layout-sensitive pages and make a contact sheet for the whole deck.
- In RTL decks with image and text split layouts, a grid inherits
direction: rtland reverses its columns. Set the split container todirection:ltrand the text area back todirection:rtl. - For mixed Persian and English slide text, prefer Persian-led phrasing and isolate short English terms; long English-led bullets often render in broken order in PDF.
Formulas in HTML
- Browsers show raw TeX delimiters (
\(...\),\[...\],$$...$$) as text unless a renderer or MathML is present. - In handwritten HTML, write native MathML; Chromium and Firefox render it offline without JavaScript:
<div class="math-display">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
<msub><mi>s</mi><mi>k</mi></msub><mo>=</mo>
<munderover><mo>∑</mo><mrow><mi>j</mi><mo>=</mo><mn>0</mn></mrow><mi>k</mi></munderover>
<msub><mi>p</mi><mi>r</mi></msub><mo>(</mo><msub><mi>r</mi><mi>j</mi></msub><mo>)</mo>
</math>
</div>Give .math-display direction: ltr and overflow: auto so wide formulas scroll inside RTL pages.
- From Markdown, or when hand-written MathML is too slow for a large document, convert with Pandoc and keep the
.mdbeside the.html:pandoc input.md -s --mathml -c style.css -o output.html. - MathJax or KaTeX is acceptable only when its script and CSS are included and verified; avoid CDN renderers unless network use is acceptable.
- A plain-text formula is acceptable only when the user does not need typeset math; explain ambiguous notation in words, for example that
G_inverse(s_k)means the inverse CDF. - Before delivery, confirm the formulas became MathML with no raw delimiters left, then open the page and check they render as math:
rg -n '<math' output.html | head
rg -n '\[|\]|\$\$' output.html | head