Design Validation — ZCode

Purpose

Turn design judgment into verifiable checks. The design-principles skill decides how to design; this skill proves the result before it ships. If any item below fails, fix it before considering the UI complete.

When to use

• After completing UI work, before declaring it done.
• Reviewing an existing UI ("does this look good?").
• Debugging visual or UX issues reported against shipped UI.

Do not use for creating or changing UI — that is design-principles.

Workflow

1. Run the application (or a live preview) — code inspection alone is not verification. Prefer an existing authorized local preview; inspect startup scripts before launching. Do not trigger seeds/migrations or restart user processes just for visual review. If no safe preview is available, complete static review and state rendered checks as not run.
2. Walk the affected flows twice: once with pointer, once with keyboard.
3. Capture screenshots at the target breakpoints.
4. Run applicable checklist items. For a review-only request, report findings without editing; for implementation work, fix in-scope defects. Mark irrelevant items N/A and unavailable checks unverified, never passed.
5. Keep non-obvious fixes documented as design decisions (see design-principles → Design Decisions).

Final Design Review

Checklist

• Existing components reused, nothing re-invented
• Responsive behavior checked at desktop, tablet, and mobile
• RTL/LTR verified: layout direction and directional icons mirror correctly
• Keyboard navigation works and focus states are visible
• Text/non-text contrast checked in applicable states, with numeric evidence or a contrast checker; do not treat exempt inactive controls as automatically requiring normal active-text contrast
• No unnecessary decoration or animation
• Matches existing product identity and design system

Tickable checks — Visual

• Spacing comes from the existing tokens, no random margins or padding
• Colors come from the token system, no raw hex scattered in components
• One clear primary action per view unless the context requires multiple equivalent actions
• New components exist only where existing patterns do not solve the problem

Tickable checks — UX

• Primary action is obvious in the first viewport
• All component states implemented (default, hover, active, disabled, loading, error, empty)
• Product-level states present where relevant (first run, empty, loading skeleton, offline, syncing, permission denied)
• Mobile and RTL behavior tested, not assumed

Tickable checks — Quality

• No placeholder-looking UI or fake data
• No inconsistent components
• No generic AI style
• Smallest change that satisfies the requirement — nothing over-engineered

Accessibility verification

• Keyboard walkthrough passes: logical tab order, every interactive element reachable and operable
• Visible focus states on all interactive elements
• No color-only meaning: status also conveyed by icon, text, or pattern
• Icon-only controls have accessible names
• Touch targets ≥ 44×44 CSS px on touch interfaces
• No unintended focus traps; modal dialogs intentionally contain focus while open and restore it on close
• prefers-reduced-motion honored

Browser reality

• No console errors
• No layout overflow at target widths
• No inaccessible interactive elements (missing roles, names, or labels)

Visual verification

• Screenshots captured at target breakpoints (desktop, tablet, mobile)
• Screenshots reviewed for alignment, spacing, and hierarchy — not just code reviewed
• Result compared against the existing product language, not an imagined ideal

Common mistakes

• Trusting that correct code means correct visuals — run it and look.
• Checking the checklist only in the happy path; walk error and empty states.
• Skipping the visual comparison against the existing product.

Validation

Record the actual widths, themes/directions and flows checked, plus failures, N/A and checks not run. Review completion is not product sign-off; a review may complete with documented defects. Only claim visual implementation validation when the applicable rendered checks were actually observed.

The Final Design Review above is the validation: fix every failed item before finishing. A UI is complete only when the checklist passes in the running application.