Problem

Documentation screenshots have three recurring visual issues across web and PDF builds:

1. Cramped element-level captures (no padding) — Element-level browser_take_screenshot produces PNGs whose content touches every edge. Example: ko/images/session_type_batch.png (2669×1770) — text and the wizard step indicator are flush against the image borders.
2. Border-radius mismatch on single-card captures — When a modal/card with its own rounded corners is cropped to its bounding box, the inner radius visibly clashes with the doc-image wrapper radius. Example: ko/images/launch_session_confirm.png.
3. Small captures stretched to full content width — A 760×190 notification is rendered at full article-column width on the web, dwarfing the actual UI. Example: ko/images/session_notification.png. PDF already auto-scales via IMAGE_SCALE_FACTOR = 0.5, but the web pipeline does not.

Affected page: https://webui-docs-next.lablup.ai/next/ko/sessions_all.html

Scope

packages/backend.ai-docs-toolkit

• markdown-processor-web.ts: mirror the PDF path — when no explicit =<width> size hint is present, read PNG dimensions via existing getImageDimensions() helper and emit style="max-width: ${dims.width / 2}px" (2× zoom capture convention).
• styles-web.ts .doc-image / figure: move border/radius/shadow from <img> to the figure wrapper; add padding and neutral background so the wrapper acts as a matte/frame around the image content.
• styles.ts (PDF): apply the same matte treatment for visual parity between web and PDF.

packages/backend.ai-webui-docs

• SCREENSHOT-GUIDELINES.md: add a "small-element rule" (capture target bounding box ≤ 600 CSS px → apply padding/background via browser_evaluate before capture, or capture a logical parent container) and a "parent-container-preferred" rule (.ant-modal-wrap over .ant-modal, panel wrapper over panel).

.claude/agents/docs-screenshot-capturer.md

• Update prompt to follow the new small-element/parent-container rules.

Out of scope (separate issue)

• alt-text policy and figcaption pipeline separation — tracked in a follow-up issue (PR B).

Verification

• Run pnpm --filter backend.ai-webui-docs run preview:html:ko and spot-check sessions_all page: the three sample images render with matte padding, no radius clash, and session_notification.png is no longer stretched to column width.
• Run pnpm --filter backend.ai-webui-docs run pdf:ko and confirm PDF output keeps visual parity with web (matte applied, captions intact).
• bash scripts/verify.sh passes.

Notes

Existing parseImageSizeHint() (![alt =500px](url)) syntax remains untouched and continues to override the auto cap when authors need explicit sizing.

JIRA Issue: FR-2907