UI Doc

Interactive UI documentation pages (ui-doc)

Produce one interactive HTML page per WinForms screen: a 1:1 mockup of the dialog, numbered badges + arrows, click-to-explain controls, and an operation-sequence walkthrough wired both ways. Output is a single self-contained HTML file (icons/images embedded as base64) that works from any browser, file share, or static host. Page-visible text follows the project language (the demo uses Traditional Chinese, zh-TW).

Start from references/template.html — it contains the full CSS token system and the JS wiring skeleton (INFO/HL/STEP_OF, select/markStep/activateStep, steps bar, sticky info card). Copy it and fill the placeholders. Details live in references/coordinate-notes.md.

Adapt the project-specific parts on install: the folders where Views/Controllers live, the meta-strip labels, and the output folder for finished pages.

Workflow

1. Investigate code → 2. Rebuild 1:1 from Designer → 3. Annotate → 4. Wire interactivity + operation sequence → 5. Run scripts/check_wiring.py → 6. Deliver.

1. Investigate the code first (never guess from a screenshot)

Find the Form by grepping window titles, control text, or localization keys. Read three files:

Screenshots are only for cross-checking real row data and AutoSize column widths.

2. Rebuild 1:1

Everything follows the Designer's control types and properties. Comment each element with its source (<!-- Button button4 (42,12) 87×35 -->).

• Coordinates: stage = dialog offset + 32px title bar + accumulated parent-container Locations (nesting math in coordinate-notes).
• Font: if the Designer sets one, use it; if not, the WinForms default applies — Microsoft Sans Serif 8.25pt ≈ 11px (CJK glyphs fall back to the system serif, e.g. 新細明體). Never apply one size to every page.
• Window chrome: Win11 title bar (rounded, grey text, —　□　✕) + drop shadow. Title-bar icon comes from the form's .resx $this.Icon (16px layer → PNG data URI); never fake it with text. Use scripts/extract-assets.ps1.
• Images: trace PictureBox images through Properties\Resources.Designer.cs to the real file and embed as base64; SizeMode ↔ object-fit mapping in coordinate-notes. Display-only images get no hot/data-i/badge/INFO — no function, no explanation.
• Faithfulness: an imageless PictureBox is invisible against the Control-grey ground — keep it invisible (give it a transparent hot area). Controls removed/hidden at runtime (removed TabPages, Visible=false, #if DEBUG) are not drawn; note them in the remarks.
• DataGridView styling (incl. DotNetBar DataGridViewX orange selection): exact colors in coordinate-notes.
• Designer settings are the drawing basis only — do not render them as a settings table on the page.

3. Annotation

• Stacking: window (bottom) → arrow SVG (z-index:5, pointer-events:none) → numbered badges (z-index:6). Arrows must paint above the window or they get clipped by it.
• Arrow endpoints must land within ±4px of the target's edge — verify by arithmetic after writing.
• Badge labels default below the circle; when circles in one column are <45px apart, move the label to the side (.lr right / .ll left).
• Number only controls with a function; decorations (logo, icon) get no badge.

4. Interactivity contract

Three tables drive everything — future edits touch only these:

• INFO: key → {n (badge no.), name, en (type + control name + coords), d (description), note}.
• HL: when one explanation binds several controls, key → extra element ids to highlight together (e.g. a tab pair, label + input, a button group). Dynamic sets ("buttons of the visible tab") are resolved inside select() via the visible container.
• STEP_OF: element key → step index, giving screen-click → step-chip reverse linkage. Leave out non-flow elements (cancel, read-only fields).

Behavioral requirements:

• Clickable elements get class="hot" data-i="<key>"; select(key) highlights all elements sharing the key plus the HL list, updates the sticky info card, and marks the step.
• Real behaviors must actually work: tabs switch (with their tab-specific badges/arrows), search boxes really filter, grid rows single-select on click (▶ + ✓ + orange highlight move), radios toggle.
• Operation-sequence bar: text-only chips, no numbers, plus ‹ › navigation. A step that applies only to one tab must be hidden and skipped on the other tab. A step with no on-screen element (the action happens in the host application's main window) says so on the info card.
• Themes: the page shell is token-based dual-theme; the window mockup is a depicted object and stays light in both themes.
• Sub-dialogs opened from the main flow get their own complete set — annotated stage, operation-sequence bar (own STEPS/STEP_OF/chips/‹›), and own sticky info card. Page order: main stage → main steps → main card → sub stage → sub steps → sub card. Route by key set: main-window keys update the main card, sub-window keys the sub card. Keep one optional "open sub-dialog" step in the main flow. Wrap each stage+steps+card in its own section container so the two sticky cards never pin at the same time.

Mandatory pre-completion audit

Navigation and reverse linkage are required features, not options. Before delivering run:

python scripts/check_wiring.py <page.html>

It must print PASS (exit 0). It checks: chips↔STEPS indices + prev/next wiring, every data-i/data-k has an INFO key, STEP_OF coverage and index range, HL/getElementById targets exist, hot elements have a click path. [info] lines about non-flow elements are expected. Also verify by hand anything the script can't see: dynamic HL sets under both tab states, and sub-dialog card routing.

Editor/IDE preview panes often render local files as static snapshots — JS does not run there. A dead click in such a pane proves nothing either way; trust the audit script and a real browser.

5. Page format & delivery

Meta strip at the top (align labels with the project's own documentation inventory), then: title + intro → annotated stage(s) (clickable) → operation-sequence bar → sticky info card → reference tables (column mappings / color codes / flow diagrams as the screen warrants).

Tools with no dialog get a flow page instead: meta strip + intro (purpose, trigger, preconditions) + .flow execution steps from the controller code + remarks; state clearly that the tool runs directly with no UI.

File name <code lowercase>-ui.html; keep published URLs stable by always redeploying the same file path; copy finished pages to the project's documentation folder.

Reference files

• references/template.html — primary skeleton: complete CSS + JS wiring with placeholders. Start every page from this.
• scripts/extract-assets.ps1 — fills __ICON_B64__ (from resx $this.Icon) and __<KEY>_B64__ (from image files) into a page. Save any hand-written .ps1 with a UTF-8 BOM or Windows PowerShell 5.1 mangles non-ASCII paths.
• scripts/check_wiring.py — the mandatory pre-completion audit.
• references/coordinate-notes.md — nesting math, runtime overrides, fonts, asset extraction, style palette, stacking, label anti-overlap.
• Live demo of the output format: docs/sample-ui.html (a fictional dialog).