WordPress journeys and visual decisions

Read references/engineering-contract.md first. Review requests stay read-only: assess, explain and recommend without edits, redesign, baseline refresh or untrusted runtime execution. Implementation applies only when the request authorizes changes.

Inputs

User task and success definition, existing screenshots and content, surface owner (theme, block, builder, admin), editable components, design constraints, supported locales, directions, browsers and devices. Inspect project evidence first; ask only what changes the decision.

Boundaries

• WCAG criterion-by-criterion conformance: wp-devkit-wcag-review; accessibility defects in code: wp-devkit-accessibility-review.
• Theme templates, theme.json mechanics: wp-devkit-theme-development; wp-admin screen implementation: wp-devkit-admin-ui-development; block internals: wp-devkit-block-development.
• Speed measurement and tuning: wp-devkit-performance-review.

Code Review Workflow

1. Capture the current journey and content (URLs, viewports, screenshots). Define the user outcome; separate visual polish from structural reconstruction.
2. Locate the owner of each surface and token (references/wordpress-ui-surfaces.md, references/design-systems-and-tokens.md). Preserve working navigation, links and content.
3. Check states, forms, layout and interaction against references/responsive-states-and-interaction.md: loading, empty, error, success, long content, 320 px to wide, zoom, keyboard, focus visibility, target size, reduced motion.
4. Check locale and RTL with stress data (references/localization-and-content-design.md).
5. Identify the evidence available for any usability, conversion or performance claim (references/research-and-usability.md, references/analytics-and-experiments.md); mark unsupported claims "not measured".
6. Report observed rendered and interaction evidence, plus proposed acceptance checks. A review does not authorize a redesign.

Read references/ui-design-workbook.md for the decision table, symptoms, false positives, severity and worked example. Use references/acceptance-checklist.md for delivery acceptance and references/visual-regression-and-devices.md for the rendering matrix, Playwright baselines, Core Web Vitals evidence and axe automation.

Implementation workflow

State the user flow and the smallest affected owner. Use existing tokens and component states; change a token at its source. Implement all states, then run the acceptance checks at the stated viewports, locales and browsers. Never refresh a visual baseline without a recorded acceptance decision. Report unrun checks as unexecuted. Deployment needs its own scope.

Search Patterns for Quick Detection

Read-only leads; no match proves nothing; a match is a candidate until rendered. Exit 0 = match, 1 = none, 2 = error.

# structure and landmarks
rg -n -g '*.{php,html,json,js,jsx,ts,tsx}' -g '!**/{vendor,node_modules,build,dist}/**' -e '<(main|nav|header|footer|h[1-6]|button)\b|wp:group|wp:columns|elementor' .
# tokens and presets
rg -n -g '*.{css,scss,json,js,ts}' -g '!**/{vendor,node_modules,build,dist}/**' -e '--wp--preset--|--wp--custom--|var\(--|"(palette|fontSizes|spacingSizes)"' .
# layout risks
rg -n -g '*.{css,scss}' -g '!**/{vendor,node_modules,build,dist}/**' -e 'width:\s*[0-9]{3,}px|min-width:\s*[0-9]{3,}px|overflow(-x)?:\s*(hidden|scroll)|@container|@media' .
# focus, motion, preferences, targets
rg -n -g '*.{css,scss}' -g '!**/{vendor,node_modules,build,dist}/**' -e 'outline:\s*(none|0)|:focus-visible|prefers-reduced-motion|forced-colors|prefers-color-scheme' .
# states and feedback
rg -n -g '*.{php,html,js,jsx,ts,tsx}' -g '!**/{vendor,node_modules,build,dist}/**' -e 'aria-busy|aria-live|role="(alert|status)"|aria-invalid|aria-describedby|disabled' .
# direction and language
rg -n -g '*.{css,scss,php,html}' -g '!**/{vendor,node_modules,build,dist}/**' -e '(margin|padding)-(left|right)|text-align:\s*(left|right)|float:\s*(left|right)|\b(dir|lang)=' .

Reading the leads: outline: none matters only when no replacement focus style exists; margin-left matters only where direction should flip; fixed pixel widths matter only when they clip at a tested width; overflow: hidden may be deliberate.

Output Format

Lead with the result and what was observed (viewports, browsers, locales, assistive tech actually used). Confirmed concern: location (file:line or URL+viewport), actor, trigger, reachable path, impact, confidence, minimal fix, regression check. Keep candidates and unmeasured claims separate. For implementation include the user flow, responsive and keyboard checks, screenshots when available, empty/loading/error/success states, commands with exit codes and unexecuted checks. A visual pass does not prove usability, conversion, screen-reader behavior or conformance.