docx-builder

A Claude Code skill that turns flowing HTML into a real, fully-editable Word (.docx) document — native headings, paragraphs with per-run formatting, lists, tables and images in document order, not a screenshot pasted into a page.

Both pages above are the actual Word output (rendered back to PNG for this README) from templates/document-template.html, included in this repo — every heading, run of bold/italic/colored text, list and table is a real, independently editable Word element once opened in Word/LibreOffice.

Part of a small family of Claude Code skills for turning designs into real, editable office files instead of screenshots-in-disguise: pptx-builder-skill (PowerPoint), pdf-builder-skill (vector PDF), and template-filler-skill (fills an existing pptx/docx template instead of building a new one).

Why this one

Word documents reflow — they aren't a fixed canvas like a slide or a PDF page. This skill reads document order and computed style, not pixel coordinates, which is a different extraction model from its sibling skills:

• A style gallery, not a blank page. templates/style-gallery.html (screenshot below) offers 8 named heading/body font + accent-color presets an agent can show before writing, so a document starts from a deliberate visual identity instead of improvised fonts section by section.
• Per-run inline formatting, not just block-level styles — bold, italic, color and mixed runs inside the same paragraph all survive the HTML → DOCX conversion.
• Verification is mandatory, not optional. verify_docx.py catches structural/XML corruption that Word would otherwise silently "repair" by dropping content; render_preview.py forces an actual look at every rendered page before the pipeline is allowed to call a document done.

How it works

Two stages:

1. Design in HTML. A normal top-to-bottom flowing page — no position:absolute, no fixed-size canvas. Elements that should become real Word blocks carry a data-docx="heading|paragraph|list|table|image| quote|page-break" attribute; the design is iterated on and approved as a live preview before anything is converted.
2. Compile to native .docx.
   • scripts/extract_docx.py opens the HTML in headless Chromium (Playwright) and walks the body in document order, recording each tagged block's type, computed style and per-run text formatting (plus list nesting depth and table cell data).
   • scripts/build_docx.py reads that JSON and builds a real python-docx document from it — page setup, running header/footer, heading levels, formatted runs, nested lists, tables and images.
   • scripts/verify_docx.py checks the output file for structural/XML corruption that Word would otherwise silently "repair" by dropping content.
   • scripts/render_preview.py renders every page to PNG (via LibreOffice
     • PyMuPDF) so the result can actually be looked at, not just assumed correct because the scripts didn't error.

See SKILL.md for the full workflow this skill makes an agent follow, reference/conventions.md for the exact HTML→DOCX contract, and reference/style-presets.md + templates/style-gallery.html for a set of 8 ready-made font/accent-color presets an agent can offer before writing. reference/icons.md ships a small line-icon library for contact rows and short feature lists.

Requirements

• Python 3.9+
• LibreOffice (soffice on PATH, or the default Windows install path) — used only by render_preview.py

pip install -r requirements.txt
playwright install chromium

Using it as a Claude Code skill

Drop this folder into a skills directory so Claude Code (or any agent runtime that supports the same skill format) can discover and use it:

# project-level (this repo/project only)
cp -r docx-builder /path/to/your/project/.claude/skills/docx-builder

# or user-level (every project)
cp -r docx-builder ~/.claude/skills/docx-builder

Then ask the agent to write a document (e.g. "draft me a report about ..."). It will design the content as HTML, show you a preview, and only run the conversion pipeline once you approve the design.

Using the scripts directly

The pipeline is plain Python and works outside of any agent, too:

python scripts/extract_docx.py document.html work/document.json work/images
python scripts/build_docx.py work/document.json output.docx
python scripts/verify_docx.py output.docx
python scripts/render_preview.py output.docx work/preview

templates/document-template.html is a working example (title, headings, mixed-formatting paragraph, nested lists, a quote, a page break, a table) to start from.

Known limits

• Not an absolute canvas — no pixel-exact placement of anything other than image/icon size. For a pixel-exact one-pager, use pdf-builder instead.
• Rich per-run formatting inside a table cell isn't supported — one style per cell.
• Numbered/bulleted lists support up to 3 nesting levels; deeper nesting falls back to a plain indented paragraph with a literal bullet character.
• No generated table of contents or running section numbers — add a TOC in Word itself once the file is open.
• Fonts are not embedded — Word substitutes at open time on whatever machine views the file if the exact font isn't installed there. Stick to common fonts (Calibri, Arial, Georgia, Times New Roman) unless the target machine is confirmed to have anything else.
• Stacking/reading order follows DOM order, not visual layering.
• data-docx="icon" elements are rasterized (a picture, not an editable shape) — use only for actual small icons/logos.

License

MIT — see LICENSE.