# CMSification checklist

This suite ships with generic, semantically-correct behaviour and nothing that assumes a
specific CMS. Making it emit your organization's real component markup and enforce your real
compliance rules is a bounded, mostly-configuration task — this doc is the checklist.

**Important:** everything the tools currently do was built from the two prototypes and the
pitch deck alone — no real client/legal documents were used or seen by any AI system in building
this. Keep it that way during CMSification: when gathering examples for the technical team (or
for a future AI-assisted pass), use synthetic/dummy content that preserves structure but not real
figures or client text, or extract the mapping rules from documentation-only sources (component
library docs, empty templates) instead of real submissions. Real documents should only ever touch
the four tools themselves, running locally — never a chat session, ticket, or shared doc.

## 1. The one file that should need real editing: `tools/03-converter/style-map.js`

Every mapping decision the Converter makes is isolated in this one object. `convert.js` is
generic body-walking logic and shouldn't need to change for a normal CMSification pass. Go
through `style-map.js` top to bottom — every `TODO-CMS` comment marks a decision point.

## 2. What to gather before editing it

1. **Paired before/after examples (highest value).** 5–10 real-shaped (or synthetic/dummy)
   Word docs alongside their already-published CMS HTML equivalents, covering your actual
   component range: body text, H1–H3, bullet/numbered lists, data tables, callout/alert boxes,
   block quotes, image + caption, footnotes-as-endnotes if used. Reverse-engineering the exact
   style→component/class mapping from pairs is far more reliable than working from a prose style
   guide alone.
2. **The component library reference** — whatever documents which WET/CMS component each content
   type should become (e.g. the `wb-tables` class + `<caption>` requirements for data tables, the
   accordion/tab markup pattern), even just the internal dev wiki page.
3. **The page shell/boilerplate** — the real chrome markup (nav, header, footer, breadcrumb) so
   `style-map.js`'s `wrapContent()` can be replaced with the real wrapper instead of the
   `TODO-CMS-CONTENT-ZONE` placeholder, and so `tools/04-validator/inventory.js`'s
   `findContentZone()`/boilerplate-stripping heuristics can be tuned to your DOM instead of the
   generic `<main>`/`role="main"`/highest-density heuristics currently in use.
4. **A definitive "CMS can't represent this" list**, from whoever owns the component library —
   feeds `tools/02-gatekeeper/checks.js` directly (nesting limits, unsupported structures), rather
   than relying on the current generic assumptions (no nested tables, no text boxes, no dynamic
   fields, etc — all defensible defaults, but not necessarily complete for your system).
5. **The actual style guide text** — sentence-case rules, terminology, banned phrases — to replace
   the heuristics in `tools/01-prep-check/checks.js`'s `sentenceCaseVerdict()` and the
   `SENTENCE_CASE_SMALL_WORDS`/placeholder-pattern lists, which currently know nothing about your
   organization's real exceptions (program names, approved acronyms, etc).
5a. **The actual design guide, specifically for italics/emphasis rules.** `checks.js`'s `italics`
   check (`ITALIC_LONG_RUN_WORDS`, currently 15 words) is a placeholder — no style/design guide
   document has been provided to this suite yet, so it encodes a generic, defensible convention
   (italics for short specific uses only, not extended passages) rather than your organization's
   actual rule. This is the most clearly "waiting on real input" check in the suite — replace or
   remove it once you have the real guide. The same applies to any other emphasis conventions
   (bold usage, when to use ALL CAPS for defined terms, etc.) the real guide specifies that aren't
   checked for at all yet.
6. **Compliance specifics**: WCAG 2.0 vs 2.1 (vs 2.2) AA, and — if this is a Government of Canada
   context — official-languages/bilingual structure requirements and French non-breaking-space
   rules. None of that is encoded yet.
7. **What "figure" means for the zero-tolerance validator.** `tools/shared/diff-utils.js`'s
   `extractFigures()` currently catches currency, percentages, plain numbers, and a handful of
   date formats via regex. If your documents use figure formats it doesn't recognize (e.g.
   fractions, ranges like "12–15%", footnote-marked figures), extend `NUMERIC_PATTERNS` there.
8. **Numbering/list styles** — if your Word templates use custom multi-level list definitions,
   confirm `tools/03-converter/convert.js`'s `parseNumbering()` (reads `word/numbering.xml`,
   `w:numFmt` at `ilvl 0` only) correctly distinguishes bullet vs. ordered lists for your templates.

## 3. Known converter limitations to harden (see also the header comment in `convert.js`)

- List nesting that skips more than one indent level in a single step only opens one extra
  `<ul>`/`<ol>` level.
- Table cells with multiple paragraphs are joined with `<br>` rather than kept as separate `<p>`s.
- Run-level formatting covers bold/italic/underline + hyperlinks + inline images only — no
  strikethrough, superscript/subscript, or text color.
- Images are currently inlined as base64 `data:` URIs for a self-contained, zero-setup preview.
  Production use should instead upload each image to your DAM/asset pipeline and rewrite `src` —
  the `data-original-filename` attribute left on every `<img>` exists specifically so a later
  script can do that rewrite without re-deriving filenames from the docx.
- `tools/02-gatekeeper/checks.js`'s `APPROVED_TEMPLATE_STYLES` set is empty — if your org's Word
  template ships additional built-in-looking styles that are pre-approved (not truly "custom"),
  add their exact style IDs there so Gatekeeper doesn't false-flag them.

## 4. Suggested order of work for the technical team

1. Collect the artifacts in section 2.
2. Fill in `style-map.js` and re-run the Converter against a handful of real (or synthetic)
   documents; compare its output HTML against the paired real examples.
3. Extend `tools/02-gatekeeper/checks.js`'s hard-blocker list with anything the component-library
   reference says the CMS truly cannot represent that isn't already covered.
4. Point `tools/04-validator/inventory.js`'s `findContentZone()` at the real page-shell selectors
   if the generic heuristics ever mis-detect the content zone on a real published page.
5. Only after 2–4 are stable, consider whether `tools/01-prep-check/checks.js`'s sentence-case /
   stray-text heuristics need the real style guide's exception lists.