# UI Doc

> 產生 WinForms 對話框的「互動式 UI 說明頁」。只要使用者貼出 WinForms 畫面截圖要求介紹、說明、標註畫面，或提到「UI 說明」「介面說明」「標註圖」「圓形編號」「操作順序」「互動式說明頁」，甚至只說「幫我做 XX 畫面的說明」，都務必使用本 skill。做法：讀 Designer.cs 依控制項設定 1:1 重繪畫面、加圓形編號＋箭頭標註、元件可點選顯示說明、操作順序步驟導覽。

- Skill: `mingfeng6684/ui-doc` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add mingfeng6684/ui-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingfeng6684/ui-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mingfeng6684 (https://skillmd.com/u/mingfeng6684)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mingfeng6684/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:

| File | What it provides |
|---|---|
| `<Form>.Designer.cs` | **The single source of truth for geometry & settings**: ClientSize, each control's type, Location/Size, BackColor, Font, Visible, events, DataGridView columns |
| `<Form>.cs` (code-behind) | Behavior: handlers, DialogResult, and **runtime text** from localization calls (often overrides Designer text) |
| the controller / caller | Data sources and the full flow behind each button |

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:

```bash
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).