` with headings inside | | **Table row/cell styling** | `background`, `color` on `` or ``; subtotal rows with `` | | **Financial / KPI tables** | Label column left-aligned, numbers right-aligned; pastel row bands | | **Flex rows/columns** | `display:flex; gap:8px` with 2–4 child divs (converted to borderless tables) | | **Multi-side bordered boxes** | `border:1px solid #ccc; padding:12px` on a div (uses a 1×1 table wrapper when needed) | | **Typography colors** | `color:#666` on subtitles, accent colors on deltas (`#2a9d8f`, `#e76f51`) | ### Tier 3 — Weak or unsupported — avoid | Pattern | Why | |---------|-----| | **Inline SVG / Canvas / `` charts** | Not rendered as vectors; use tables, describe data in text, or enable **`rasterizeInPlace`** when exporting from a live rendered page (recommended: `{ scale: 2 }` for chart quality) | | **CSS bar charts inside cells** | `` in `` does not port | | **Emoji as UI icons** | Font/glyph mismatch in Word | | **External stylesheets** | Only inline `style=""` and a few attributes (`border`, `cellpadding`, `colspan`) | | **Grid / absolute / float layout** | No `position`, `float`, `grid-template` | | **CSS `transform` / arbitrary text rotation** | Intentionally out of scope. `transform: rotate(45deg)` and all other `transform` functions are ignored. Word cell text direction (`w:textDirection`) supports only 90° orientations, so diagonal/angled text has no native, in-flow equivalent — it would require a floating shape, which breaks editability and is not emitted. | | **Multi-column CSS** | No `column-count` | | **Web fonts** | Defaults to Arial; custom `@font-face` ignored | | **Forms, inputs, buttons** | Not supported | | **Deeply nested layout divs** | Prefer flat block flow: heading → p → table → p | | **`` / ``** | Column widths inferred from content, not col tags | --- ## HTML style guide for agents ### Page and typography defaults The engine assumes **US Letter**, **1″ margins**, **Arial 14px**, **line-height ~1.4** when CSS does not set one. Set `line-height` on paragraphs and headings to match Google Docs presets (`1`, `1.15`, `1.5`, `2`) or any unitless multiplier. You do not need a wrapper document; if you preview in a browser, match: ```html ``` Use **hex colors** (`#1a1a2e`, `#666`, `#f5f5f5`). Named CSS colors work when parsed, but hex is predictable. ### Block structure Prefer a **linear document flow**: ``` h1 title p subtitle (muted color, smaller font-size) table | ul | blockquote h2 section p … ``` Each visual “section” should be a heading or table—not a tower of anonymous divs. **Good — shaded hero:** ```html

Sprint 24 Retrospective

Platform Team · Mar 3 – Mar 14, 2026

``` **Bad — layout soup:** ```html
…
``` ### Tables (data, not layout) Use tables for **tabular data only**. Always include: - `border="1"` (or explicit border in style) when grid lines are wanted - `cellpadding="6"` or `8` - `style="border-collapse:collapse;width:100%"` - Header row with `` labels - `text-align:right` on numeric `` cells **Good — financial row bands:** ```html

Line item Q1 2026

Subtotal $33,424

``` Put **text inside cells** (``, ``)—not nested layout divs, charts, or icons. ### Inline vs block backgrounds | Intent | HTML | DOCX mapping | |--------|------|----------------| | Highlight a phrase | `text` | Shading on `TextRun` | | Banner / callout / row band | `background` on ``, ``, or `` | Paragraph or cell shading | | Whole paragraph tint | `background` on `
` | Paragraph shading | Keep inline highlights **short** (a few words). Long shaded spans across line wraps are OK but may differ slightly from browser wrapping. ### Lists - Use `
` / `
` for enumerations, action items, roadmaps - Keep list item content in inline flow; avoid block elements inside `
` when possible - Nested lists are supported (ordered inside unordered, etc.) ### Links ```html
See the full report for details.

Jump to the appendix.
…
Appendix
``` Links render as Word hyperlinks (underlined, Hyperlink style). External URLs use relationship-based hyperlinks; `href="#id"` becomes an internal jump to the element with that `id` (or a legacy ``). ### Flex (simple only) Supported for **small toolbars, KPI chips, column stacks**: ```html

Left

Right

``` Do **not** use flex for page layout, sticky headers, or precise pixel alignment. Max ~4 items per row. ### Line breaks and addresses ```html
742 Evergreen Terrace
Springfield, OR 97403
``` `
` is supported inside paragraphs. Do not simulate line breaks with empty `
` tags. --- ## Supported inline CSS properties Parsed from `style=""` on any element: | Property | Example | |----------|---------| | `color` | `color:#666` | | `background` / `background-color` | `background:#f5f5f5` | | `text-align` | `left`, `center`, `right`, `justify` | | `font-size` | `13px`, `12px` (px preferred) | | `line-height` | Unitless (`1.5`, `2`), `%`, `px`, `pt`, `em` — paragraph line spacing | | `font-weight` | `bold`, `600` | | `font-style` | `italic` | | `margin`, `margin-*` | `margin-top:0`, `margin:8px 0` | | `padding`, `padding-*` | `padding:8px`, `padding-left:12px` | | `border`, `border-*` | Blockquote left rule, boxed sections | | `display` | `flex`, `block`, `inline-block` | | `flex-direction` | `row`, `column` | | `gap` | `gap:10px` (px; converted to twips internally) | | `width` | `width:100%` on tables | Everything else is ignored silently. --- ## Supported elements | Element | Role | |---------|------| | `h1`–`h6` | Headings (mapped to Word heading levels; default text color matches body `#111`, not Word theme blue) | | `p` | Body paragraphs | | `div`, `section` | Block containers; shading and padding | | `ul`, `ol`, `li` | Bulleted / numbered lists | | `table`, `tr`, `td`, `th` | Data tables (`colspan` supported) | | `thead`, `tbody`, `tfoot` | Table structure (rows collected) | | `blockquote` | Indented quotations | | `hr` | Thematic break | | `break-before: page`, `break-after: page` | Explicit page breaks — see [API.md](./API.md#supported-html--css) | | `page: portrait \| landscape \| Name` | Per-section orientation on top-level blocks (inline path); class→page rules need `styleSource: "computed"` — [API.md](./API.md#mixed-page-orientation) | | `strong`, `b`, `em`, `i`, `u` | Inline emphasis | | `a` | Hyperlinks | | `span` | Inline color / background | | `code` | Monospace inline text | | `br` | Line break within paragraph | | `pre` | Monospace block (limited) | Unsupported tags are treated as generic block containers or skipped. --- ## Document archetypes (copy these shapes) ### Memo / policy essay (~92% fidelity) ``` h1 title p routing line (To / From / Date — muted) table routing metadata (2 columns) h2 section p body blockquote excerpt ol requirements p closing ``` ### Financial statement (~83% fidelity) ``` h1 company p subtitle (period, units — small gray) table 4-column grid, shaded header + subtotal rows p footnote with inline highlight + link ``` ### Product one-pager (~78% fidelity) ``` div hero banner (shaded) table KPI metrics (2–4 columns) table funnel stages (label + value columns) ol roadmap milestones p contact line ``` ### Retro / action tracker (~90% fidelity) ``` div banner h2 + ul (went well / to improve) table Owner | Action | Status with row backgrounds ``` --- ## Page chrome fields (headers / footers) Dynamic page numbers and section counts belong in **`headerHtml`**, **`footerHtml`**, **`coverHtml`**, or **`tocHtml`** — not in the body fragment. Use native Word fields via a marker span (the primitive): ```html
Page of
``` **Allowlist** — `data-docx-field` accepts exactly these names (case-insensitive): | Value | Meaning | |-------|---------| | `page` | Current page number | | `pages` | Total page count | | `section-pages` | Pages in the current section | | `section` | Current section number | **Sugar:** `{page}` and `{pages}` in chrome HTML or in the `pageNumber` option string lower to the same markers. `pageNumber: true` is shorthand for `"Page {page}"`. **Not supported:** arbitrary Word fields (merge fields, dates, doc properties, external links). Those values are known at convert time or belong in your source HTML as plain text — put the date, author name, title, or merge placeholder string directly in the body or chrome markup (e.g. `
March 14, 2026
`, `© 2026 ACME`) rather than as a live field. Unknown `data-docx-field` values emit a warning and are dropped. Body content cannot use fields in v1. --- ## Agent checklist before convert - [ ] Fragment is **body content only** (no ``, scripts, or external CSS) - [ ] **Tables** used for data, not page layout; numeric columns right-aligned - [ ] **Backgrounds** on `span` (inline) vs `div`/`tr`/`td` (block) used intentionally - [ ] **No SVG, images, emoji icons, or CSS drawing** inside tables - [ ] **Headings** encode document structure (`h1` once, then `h2` sections) - [ ] **Colors** are hex; contrast readable (light text on dark row bands) - [ ] **Links** have `href`; important labels use `` not custom font hacks - [ ] **Flex** limited to simple rows/columns with ≤4 items - [ ] Run `npm run typecheck` after pipeline changes; smoke-test with `convertHtmlToDocx` --- ## Validation commands (human or CI agent) ```bash npm run typecheck # TypeScript npm run score:suite # full suite: visual + XML + editability (cases: tools/generator.ts) npm run score:suite:priority # fast subset of the same cases npm run showcase # 6 rich real-world examples ``` After conversion, OOXML should pass schema validation. For critical documents, open `output.docx` in Word and verify tables are editable cell-by-cell and lists use native numbering. --- ## Minimal starter template ```html
Document Title

Subtitle or date line

Section
Opening paragraph with emphasis and a link.

First point

Second point

Column A Column B

Row label 123

Footnote with highlighted term.
``` --- ## Mental model ``` Browser HTML (layout engine) ≠ Word (flow + styles + tables) dom-docx maps a practical subset: semantic blocks → native OOXML ``` Agents should generate HTML that would still read well as a **printed memo**—not HTML that only makes sense with CSS layout engines, JavaScript, or embedded graphics. When in doubt: **heading, paragraph, table, list, span highlight.** That path produces the highest-fidelity, most editable DOCX.