WordPress 7.1 themes can configure mobile and tablet viewports instead of relying only on the defaults. Values that use unsupported units, fail parsing, or place tablet at or below mobile can be ignored or reduce the available responsive states.
Use this for agencies and theme teams that need their WordPress breakpoints to match an established design system, device matrix, or existing CSS framework.
Quick answer
Define mobile and tablet values in px, em, or rem, keep tablet greater than mobile, and test the pixel immediately below, at, and above each resolved boundary. Confirm the editor preview label, generated CSS, and frontend computed values agree. Invalid values should be caught in review before they silently fall back.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Default | No custom viewport settings | Mobile and tablet use Core defaults of 480px and 782px |
| Pixels | mobile 520px, tablet 900px | Both states are available and change at those boundaries |
| Relative units | mobile 32rem, tablet 56rem | Resolved thresholds match the expected root font size |
| Invalid order | mobile 800px, tablet 700px | Tablet state is not treated as a valid larger viewport |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Map design tokens | Record the current design-system breakpoints and the root font size used to resolve em or rem values. | Configured values use px, em, or rem with valid numeric values. |
| Validate units and order | Confirm the configured tablet value resolves above the mobile value. | Tablet resolves above mobile. |
| Build boundary fixtures | Add deliberate invalid fixtures with unsupported units, missing units, and reversed thresholds. | Editor preview and frontend CSS use the same intended boundaries. |
| Compare editor and frontend | Test CSS output and computed values one pixel below, at, and above each breakpoint. | Critical components pass below, at, and above both thresholds. |
What to check first
- Record the current design-system breakpoints and the root font size used to resolve em or rem values.
- Confirm the configured tablet value resolves above the mobile value.
- Add deliberate invalid fixtures with unsupported units, missing units, and reversed thresholds.
- Test CSS output and computed values one pixel below, at, and above each breakpoint.
- Check editor previews and frontend pages with the same block fixture and browser zoom.
Field notes
- Record both the configured value and its resolved pixel boundary.
- Keep browser zoom and root font-size rules stable during comparison.
- Test long text, navigation wrapping, columns, and image cropping at each edge.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
{
"version": 3,
"settings": {
"viewport": {
"mobile": "32rem",
"tablet": "56rem"
}
}
}
Why this usually happens
- Design tokens can be copied without their unit or with a unit that the setting does not accept.
- Relative units depend on font-size assumptions that screenshots may hide.
- A tablet threshold at or below mobile cannot describe a distinct larger range.
Decision rule
Do not ship when a configured value is ignored, the tablet range disappears, relative units resolve differently than expected, or a critical component changes outside the approved boundary.
Production verification checklist
- Configured values use px, em, or rem with valid numeric values.
- Tablet resolves above mobile.
- Editor preview and frontend CSS use the same intended boundaries.
- Critical components pass below, at, and above both thresholds.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Map design tokens
- Validate units and order
- Build boundary fixtures
- Compare editor and frontend
- Document the approved thresholds
Mistakes to avoid
- Do not test only common device presets.
- Do not compare rem values without recording the root font size.
- Do not assume an invalid value will produce a visible warning on every screen.
- Do not set breakpoints from device names alone when content wraps earlier.
Questions teams ask during testing
What are the default values?
The Core dev note lists 480px for mobile and 782px for tablet.
Which units are accepted?
The documented setting accepts px, em, and rem values.
What happens when tablet is not larger than mobile?
Only the mobile state is available because there is no valid larger tablet range.
What to tell the client or owner
Record the theme.json value, root font size, resolved pixels, browser zoom, viewport, generated rule, computed value, affected block, and expected design token.
When HandL WP should help
HandL WP can align WordPress viewports with a design system, build boundary fixtures, identify ignored values, and verify the editor and public site at exact thresholds.
If this is active on a production site, validate WordPress responsive breakpoints.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references