In a Drupal theme a "small screen" is not a phone — it is any container narrower than roughly 576 CSS pixels, and most of the time that container is a region, not the browser window. That distinction is why responsive bugs survive a device check. You drag the window narrow, everything reflows, you sign it off — and then a content editor drops a three-column Views block into a 280-pixel sidebar and the layout falls apart on a 1920-pixel monitor, where no media query is watching.
Every number below was read out of a file — Drupal 11.4.6 core, plus two themes and one module I maintain.
What a small screen actually measures now
The familiar "320px to 480px" definition describes a generation of phones that has largely gone. Replace it with numbers you can point at.
- Solo declares its ladder in JavaScript at
js/components/solo-scripts.jslines 19–26: 260, 320, 576, 768, 992, 1200. Anything under 576 gets the body classsmall-screen. So in Solo, "small" ends at 576, not 480. - Olivero, core's front-end theme, declares eight breakpoints in
core/themes/olivero/olivero.breakpoints.yml. The smallest ismin-width: 500px, the largestmin-width: 1440px. Core describes nothing below 500 at all. - VVJ Tabs, a Views display-format module I maintain, ships five optional breakpoint stylesheets at 36rem, 48rem, 62rem, 75rem and 87.5rem — 576, 768, 992, 1200 and 1400 pixels at a 16-pixel root.
Two things follow. Solo and VVJ Tabs agree on 576, 992, 1200 and 1400; Olivero shares only 1200 with them and nothing else. Three codebases for the same CMS, one common boundary between all of them — so there is no canonical Drupal breakpoint set to look up. And notice the rem values: VVJ Tabs pairs every min-width: 36rem rule with a max-width: 35.99875rem companion, 0.02 pixels below the boundary. That number exists because min-width: 576px and max-width: 576px both match at exactly 576 and the last one wins. If a submenu flickers at one specific width, this is usually the cause.
Why the viewport is the wrong ruler in Drupal
A WordPress theme mostly renders one content column, so viewport width and content width track each other. Drupal does not work that way. Solo alone exposes 25 regions, and a site builder can place any block into any of them without telling you.
So the same Views block renders at 1100 pixels in Content, at 280 in Left Sidebar and at maybe 340 in Footer Second — same page, same viewport. A media query cannot tell those three apart. It only knows how wide the window is.
Solo's answer is to measure the region. The pass at js/components/solo-scripts.js lines 102–140 walks every .region-inner, reads getBoundingClientRect().width, and stamps it with an exact class (region-s, region-m) plus cumulative maximums (region-max-576, region-max-768). The stylesheet then targets the region: css/breakpoints/solo-responsive.css carries rules like .region-inner.region-max-576 .views-exposed-form, so an exposed filter form stacks because its region is narrow, whatever the window is doing. CSS container queries are the better long-term tool for exactly this, but the principle is the same either way — in Drupal, style the container. If you organise stylesheets by responsibility, this belongs in the layout layer, which is the argument behind SMACSS-based CSS categorization for Drupal 11 theming.
If you are picking a breakpoint set for a build rather than debugging one, that decision is cheaper to get right at the start — see Drupal theming.
Three breakpoint systems, and only one of them makes CSS
This is the misunderstanding that costs Drupal themers the most time.
1. Your stylesheet's media queries
Plain CSS. These are the only breakpoints that change how anything looks. Nothing in Drupal generates them or knows they exist.
2. THEME.breakpoints.yml
This file produces no CSS at all. It feeds the Breakpoint API, and in core exactly two modules consume it. I checked by grepping every .info.yml in core 11.4.6 for a dependency on breakpoint: Responsive Image and Toolbar are the whole list. If you add an entry here and nothing changes on the page, that is correct behaviour, not a bug. The two lists need not agree, and in Solo they do not — solo.breakpoints.yml has a 414 with no stylesheet, and css/breakpoints/ has a 768 stylesheet with no API entry. Both are fine, because they answer different questions.
3. Responsive image styles
Configured at Configuration → Media → Responsive image styles, these map a breakpoint to an image style and emit a real <picture> element; the markup is in core/modules/responsive_image/templates/responsive-image.html.twig. Each mapping is one of two types, documented at ResponsiveImageStyle.php lines 76–82: image_style for art direction, one chosen crop per breakpoint, or sizes for resolution switching, where you supply a sizes attribute and let the browser pick from a srcset. On small screens sizes is almost always the right one, and it is the largest single win available on a phone — sending a 1600-pixel hero to a 390-pixel viewport is pure waste. It is the first thing I check when a site is slow; more in 5 simple ways to make any website faster.
Four small-screen failures I keep finding
- The Views table. Six columns cannot reflow. On a phone the page either scrolls sideways or the text is crushed. The fix is a second Views display in unformatted or grid format, chosen by region width — not a CSS hack on the table.
- The exposed filter form. Most themes lay exposed filters out in a row — Claro uses flexbox for them, and core's own Views stylesheet says nothing either way. Four filters plus a submit button will not fit in 390 pixels, and the overflow lands on the whole document.
- The admin theme. Editors work on phones. Claro is responsive; a heavily customised node form with a fixed-width sidebar often is not. Test
/node/addnarrow, not just the front end. - Hiding instead of reflowing. A
display: noneon a menu or a column is a rendering decision with real consequences for what assistive technology can reach — see display: none vs visibility: hidden for dropdown menus before you reach for it. Fixed pixel widths cause the same overflow more honestly: onewidth: 720pxon a wrapper overflows at every width below 720. Utility classes remove the temptation to hand-write the number, which is the idea behind UtiliKit, a utility-first CSS framework for Drupal 11.
A ten-minute check
- Load the site at a 320-pixel viewport. WCAG 2.1 success criterion 1.4.10 (Reflow) uses 320 CSS pixels as the width at which content must not require two-dimensional scrolling. A horizontal scrollbar there is a defect, not a preference.
- Zoom to 400%. Same requirement from the other direction, and it catches different bugs.
- Put your busiest block into your narrowest sidebar on a wide monitor. If it breaks there, no amount of phone testing would have found it.
- Compare the transferred size of your largest image against the space it occupies.
When to do this yourself, and when to bring someone in
Adjusting breakpoints in a sub-theme, adding a second Views display for narrow regions and configuring a responsive image style are site-builder work. If you have a working sub-theme, do them yourself.
Bring in help when the problem is structural: one component serving five regions at five widths, a Layout Builder page where any block can go anywhere, an inherited theme with hundreds of overlapping media queries and nobody sure which are live, or an audit returning reflow failures against a deadline. Those are architecture problems wearing a CSS costume — what a Drupal themer does sets out that side of the work.
Common questions
Should I use px, em or rem in media queries?
Use rem. A query in px ignores the reader's browser font-size setting; one in rem respects it, so someone using larger text gets the narrower layout at the point their text actually needs it. Note that rem inside a media query resolves against the browser default, not against your html rule.
Is 320px still a real device width?
Few phones ship at 320 CSS pixels now, but it stays the right test width: it is the WCAG reflow target, and 400% zoom on a 1280-pixel window produces the same effective width. Treat it as an accessibility floor, not a device.
Why does it look right in the device simulator and wrong on a real phone?
The simulator emulates viewport width, which is the variable least likely to be your problem. It does not reproduce a narrow region, a long unbreakable string in an editor-supplied field, or a third-party embed that sets its own width. Test the region, with real content.
Next step
Run the 320-pixel pass on your own site first; it usually finds something. If what it turns up is bigger than a stylesheet fix, look at work I have shipped, or tell me what broke and I will say whether it is a half-day job or a theme problem.
