ui-craft-checks

# ui-craft-checks

Use this comprehensive gate for formal review, QA, launch handoff, exact-fidelity inspection, high-risk complex UI, or when the fast gate exposes a deeper craft problem. Ordinary single-screen work uses `ui-design-executor` and its bundled validator without loading this full matrix. Pair standalone artifacts with `ui-artifact-workspace` when this specialist is triggered.

This skill does not replace `ui-html-renderer` or `ui-design-review`. It tells them what must be checked before delivery.

Run the gate internally by default. Surface the full checklist only for review, handoff, QA, or when the user asks for the detailed pass/fail matrix.

## When To Use

Use this skill when:

- The user asks for a formal review, QA matrix, hardening, launch-readiness, accessibility audit, or detailed handoff.
- Exact screenshot/design-source fidelity needs comprehensive validation.
- A complex form, live/data surface, or composite interaction is high risk or has failed the fast gate.
- The user explicitly requests a full craft or anti-template critique.

For ordinary single-page delivery and tiny text-only answers, skip this skill.

## Severity

- `P0`: Must fix before final delivery.
- `P1`: Should fix before production or stakeholder review.
- `P2`: Polish; fix when scope allows.

## P0 Gates

The artifact fails the craft pass if any P0 is present:

- **Not HTML by default**: a UI/design deliverable is only prose, PNG, SVG, Markdown, or a raw asset gallery when the user did not request that final format.
- **Explicit format ignored**: the user requested a non-HTML final format but the artifact silently substitutes HTML or another format for it.
- **Detached revision**: a normal follow-up creates a new sibling or regenerates an unrelated artifact instead of inspecting and patching the canonical artifact in place, losing accepted content or user edits.
- **Broken artifact boundary**: a standalone deliverable has no stable artifact directory or valid manifest/entry, or it depends on missing local files, machine-specific absolute paths, undeclared secrets, or an unmentioned build step that prevents sharing or packaging.
- **Source drift**: screenshot, Figma/design-source, or explicit contract structure is replaced by an unrelated dashboard, table, chart, sidebar, pricing page, or kanban board.
- **Missing critical states**: a data-fetching or data-transforming surface does not implement reachable loading, populated, empty, error, and edge/partial states. Mentioning them in rationale while shipping only populated DOM still fails.
- **Broken form validation**: required fields lack labels/helper/error wiring, or the prototype omits pristine, dirty/touched invalid, submitted-pending, recoverable server-error, or success behavior that the workflow can reach. A user-requested success/failure outcome that exists only in an untriggered branch still fails.
- **Keyboard/accessibility failure**: interactive controls are not keyboard reachable, focus-visible is absent, icon-only controls lack names, or native elements are replaced with inert divs.
- **Unsafe live data**: live-ready artifacts persist tokens, credentials, cookies, auth headers, raw provider responses, or secret-like fields.
- **Text/layout collision**: text overlaps controls, is clipped without intent, or mobile layout hides the primary action.
- **Broken HTML/runtime**: invalid or malformed HTML, unclosed critical tags, inline JavaScript syntax/runtime errors, or missing root content causes a blank or unusable first render. Inline event handlers nested inside `innerHTML` strings are a P0 because their quote/escape layers are fragile. Mutating cached element-reference maps to redirect a renderer, clearing a container before querying/moving its former descendants, or wrapping only `addEventListener("DOMContentLoaded", init)` in `try/catch` while leaving the later callback unguarded is also P0; use immutable references, detached fragments, one safe commit, a genuinely guarded initializer, and data hooks plus listeners/delegation.
- **False capability claim**: the response claims Figma import, connector refresh, external-browser validation, or accessibility checks happened when they did not.
- **Invented evidence**: sample metrics, placeholder records, inferred copy, or guessed assets are presented as observed source content or production data.
- **Raster route bypassed**: a requested original raster asset is replaced by an inline SVG/gradient or the whole UI is delegated, even though the dedicated raster capability is available. The asset brief also fails if its stated aspect ratio conflicts with its pixel dimensions, or if it names a save path without wiring that relative raster path and an honest fallback into the HTML.

## P1 Gates

Fix or explicitly note these before handoff:

- **Contrast and focus**: body text, muted text, control borders, semantic status, and focus rings need sufficient contrast.
- **State composition**: empty states need a headline, explanation, and recovery action; errors need what happened, why, and how to recover.
- **Typography hierarchy**: hierarchy should use at least two vectors such as size, weight, spacing, color, position, or grouping; avoid both flat hierarchy and noisy hierarchy.
- **Motion discipline**: motion should explain state, space, or feedback. Avoid ambient motion in work tools. Translate/scale/rotate/parallax motion should respect reduced motion.
- **Form timing**: do not show error chrome on pristine fields; validate after blur/submit, then clear errors as the user fixes input.
- **Responsive behavior**: navigation, filters, tables, side panels, fixed boards, and action bars need a defined mobile behavior.
- **RTL/bidi readiness**: for multilingual or unknown user-generated content, prefer logical properties and isolate unknown-direction text with `dir="auto"` or `<bdi>`.
- **AI-template tells**: remove unjustified purple-blue glow gradients, generic 3-card rows, stock-placeholder image