ui-html-renderer

# ui-html-renderer

Use this specialist for unusually complex stateful HTML, blank/runtime-risk repair, strict source-to-HTML fidelity, reusable component galleries, brand boards, or detailed implementation handoff. Ordinary single-page HTML uses `ui-design-executor`, which already preserves HTML-default delivery and baseline runtime/accessibility rules.

Pair standalone output with `ui-artifact-workspace`. It owns the stable directory, `artifact.json`, revision continuity, relative assets, and packaging boundary. This skill owns what the HTML renders and whether it works.

Skip this skill for meta work about the agent itself: analysis, options, debugging prior runs, prompt/skill review, or planning can be answered in prose unless the user asks for an HTML artifact.

Pair with `ui-craft-checks` only for formal review, QA, launch handoff, exact-fidelity inspection, or high-risk complex UI. Otherwise return to the executor's fast gate.

## Contract Input

When `ui-design-contract` has been used, treat its contract snapshot or `DESIGN.md` as the source of truth for the HTML pass:

- Apply any `ui-design-source` handoff as fidelity input: preserve frame map, visible copy, component mapping, tokens, and the chosen fidelity mode.
- Follow the named visual direction, token roles, component families, anti-patterns, and acceptance gates.
- Apply any `ui-reference-packs` selection as style guidance only: translate its density, type rhythm, color roles, and component behavior into original HTML.
- Preserve observed screenshot structure before applying inferred style changes.
- Carry forward keep/change/do-not-copy boundaries; do not embed protected logos, copied layouts, or proprietary assets unless the user owns and supplied them.
- If the contract has unknowns, either label them in the artifact or ask one focused question before rendering when the missing answer would change the page structure.
- If the contract conflicts with a generic artifact type such as dashboard, kanban, or pricing page, the contract wins unless the user explicitly overrides it.
- If a selected reference pack conflicts with the contract, existing app tokens, or visible screenshot structure, the pack loses.

## Rendering Rule

Default final output is HTML for design artifacts. If the user asks for any of these and does not explicitly request another final format, produce HTML:

- Design brief.
- UI design.
- Redesign.
- Mockup.
- Page design.
- Dashboard design.
- Component set.
- Design-system sample.
- Logo design.
- App icon.
- Wordmark.
- Brand mark.
- Visual identity.
- Figma or screenshot to UI handoff.
- Screenshot or image-based redesign.
- UI review or visual audit.
- Visual polish proposal.

Valid HTML outputs:

- A self-contained HTML artifact/file when no target repo implementation is requested.
- A rendered target app screen when the user asks to implement inside an existing app.
- An HTML review page or annotated HTML artifact for reviews.

Other final formats such as standalone images, SVG files, PDFs, Markdown-only strategy, or code-only patches are valid only when the user explicitly asks for them. Do not deliver only prose, standalone images, or a raw asset gallery by default.

Do not force HTML for non-deliverable discussion, such as "why did the agent do that", "list possible integrations", "analyze this workflow", or "first give me a plan".

## HTML Artifact Requirements

The HTML draft should be self-contained unless the repo already has an asset pipeline or splitting files materially improves later edits:

- Inline CSS for standalone drafts.
- No remote runtime dependencies.
- Realistic domain content. Label sample or inferred data; never make invented metrics look observed or production-backed.
- Reachable empty, loading, error, selected, and disabled implementations where relevant; prose state inventories do not count.
- Desktop and mobile responsive behavior.
- Stable dimensions for repeated items, toolbars, grids, cards, counters, boards, and fixed-format widgets.
- Accessible labels for controls and icons.
- Visible focus states.
- Text that wraps, truncates, or scales deliberately without overlap.
- Parseable HTML structure and inline JavaScript that does not block first render.

Use semantic HTML where practical. Add lightweight JavaScript only for preview interactions such as tabs, filters, menus, theme toggles, or sample state changes.

## State Proof Protocol

For non-trivial data surfaces, implement the relevant states in the artifact rather than describing them outside it:

- Data workflows normally need populated, loading, empty, error, and partial/stale variants.
- Forms normally need pristine, dirty/touched invalid, submitted-pending, recoverable server error, and success variants. Each explicitly requested outcome must be reachable; a helper whose failure branch is never invoked is not state proof. After validation or server/import failure, focus the first invalid field or an error summary when practical, and always announce the error through an appropriate live/alert role.
- Tabs and other composite controls need semantic selected state plus their expected keyboard model; tabs include arrow-key navigation, not only click handlers.
- Disabled, permission-gated, offline, and mobile-collapsed states are required when the brief can reach them.

Keep these states inspectable without turning the product UI into a demo panel. Use the real workflow when practical; otherwise add a compact preview-only state switcher, a `data-ui-state` rendering branch, or a clearly separated state gallery. Every state must have actual DOM/component/rendering evidence and recovery behavior. A bullet list of intended states is not implementation.

## Runtime-Safe Event Wiring

- Prefer semantic static markup with `addEventListener`, event delegation, or `data-action` hooks.
- Never put inline `onclick`/`onchange` handlers inside HTML strings assigned through `innerHTML`; nested quote/backslash layers are a commo