WordPress 7.1 lets theme authors define responsive breakpoints in theme.json. Existing themes often already have Sass variables, utility classes, block CSS, plugin breakpoints, and page-builder controls. A migration can create overlapping media queries, stale generated CSS, editor-preview differences, or a layout that changes at an unexpected width.
Use this for block themes, hybrid themes, agency design systems, multisite theme packages, and sites where plugins or builders add their own responsive controls.
Quick answer
WordPress 7.1 theme.json Custom Breakpoint Migration Test should be handled with a narrow evidence-first workflow: inventory breakpoint sources, choose one token map, regenerate and purge, then verify the result before making broader changes.
What to check first
- Inventory every current breakpoint from theme.json, CSS, Sass, JavaScript matchMedia calls, block styles, plugins, and page-builder settings.
- Define the intended breakpoint names, pixel values, ordering, and ownership before changing theme.json.
- Generate styles on staging, clear theme and CDN caches, then compare the editor canvas and public page at each boundary plus one pixel on either side.
- Test navigation, columns, grids, typography, images, forms, tables, sticky elements, focus order, and horizontal overflow.
- Inspect cascade order and duplicate media queries so old CSS does not override the new responsive controls.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Inventory breakpoint sources | Inventory every current breakpoint from theme.json, CSS, Sass, JavaScript matchMedia calls, block styles, plugins, and page-builder settings. | Theme and plugin breakpoint sources match the approved token map or have a documented exception. |
| Choose one token map | Define the intended breakpoint names, pixel values, ordering, and ownership before changing theme.json. | Editor and frontend layouts agree at every tested boundary. |
| Regenerate and purge | Generate styles on staging, clear theme and CDN caches, then compare the editor canvas and public page at each boundary plus one pixel on either side. | No horizontal overflow, hidden control, broken focus order, or large unexpected layout shift appears. |
| Test boundary widths | Test navigation, columns, grids, typography, images, forms, tables, sticky elements, focus order, and horizontal overflow. | Cache purges are no longer required for ordinary content edits after the migration. |
Why this usually happens
- A breakpoint value can be duplicated across PHP, JSON, CSS, and JavaScript.
- Generated global styles may stay cached after theme.json changes.
- Plugins can load later media queries with equal or greater specificity.
- Editor iframe width and public viewport behavior may not be identical at the same nominal breakpoint.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
breakpoint_matrix:
- width: 767
expected: mobile
- width: 768
expected: tablet
- width: 1023
expected: tablet
- width: 1024
expected: desktop
capture: [computed_style, overflow, focus_order, screenshot]
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Inventory breakpoint sources
- Choose one token map
- Regenerate and purge
- Test boundary widths
- Remove conflicting rules
Decision rule
Do not migrate until every active breakpoint has a named owner. Approve only when editor and frontend results match at boundary widths and no component depends on an undocumented legacy media query.
What to tell the client or owner
Provide the token map, old and new values, affected components, generated CSS locations, cache layers, boundary screenshots, computed styles, and any plugin exception.
Production verification checklist
- Theme and plugin breakpoint sources match the approved token map or have a documented exception.
- Editor and frontend layouts agree at every tested boundary.
- No horizontal overflow, hidden control, broken focus order, or large unexpected layout shift appears.
- Cache purges are no longer required for ordinary content edits after the migration.
Mistakes to avoid
- Do not search only compiled CSS and ignore JavaScript matchMedia calls.
- Do not test only common device presets.
- Do not remove legacy rules before identifying dependent components.
- Do not approve screenshots without keyboard and overflow checks.
Questions teams ask during testing
Should breakpoints match device names?
Prefer design-system behavior over specific devices. Names such as compact, medium, and wide can age better, but the team must still document exact values and component expectations.
Why test one pixel on each side?
Boundary errors often come from mixed min-width and max-width rules. Testing adjacent pixels exposes gaps and overlaps that a standard preset can miss.
When HandL WP should help
HandL WP should help when a theme.json migration changes many templates or conflicts with builder and plugin CSS. We can inventory the responsive sources, run boundary tests, and stage a controlled rollout.
If this is active on a production site, migrate WordPress responsive breakpoints safely.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references