Use when building responsive layouts with Tailwind CSS, picking between viewport breakpoints (sm/md/lg/xl/2xl) and container queries (@sm, @md, named @container/name), targeting a breakpoint range with max-* variants, using arbitrary breakpoints (min-[400px], max-[800px]), customising the default breakpoint set, or migrating a v3 codebase that installed @tailwindcss/container-queries to v4 where container queries are built-in. Prevents the mobile-first mistake (sm:text-center hiding text on mobile), the v3-to-v4 plugin trap (forgetting to remove the container-queries plugin in v4 still works but emits warnings), and the named-container scoping mistake (@sm:flex bleeding across nested @container parents). Covers viewport breakpoints, max-* range targeting, arbitrary breakpoints, custom breakpoint registration (v3 theme.screens vs v4 @theme --breakpoint-*), container queries (built-in v4 vs plugin v3), named containers, the full @3xs through @7xl scale, and container-query length units (cqw, cqh, cqi, cqb). Key
Use when building responsive layouts with Tailwind CSS, picking between viewport breakpoints (sm/md/lg/xl/2xl) and container queries (@sm, @md, named @container/name), targeting a breakpoint range with max-* variants, using arbitrary breakpoints (min-[400px], max-[800px]), customising the default breakpoint set, or migrating a v3 codebase that installed @tailwindcss/container-queries to v4 where container queries are built-in. Prevents the mobile-first mistake (sm:text-center hiding text on mobile), the v3-to-v4 plugin trap (forgetting to remove the container-queries plugin in v4 still works but emits warnings), and the named-container scoping mistake (@sm:flex bleeding across nested @container parents). Covers viewport breakpoints, max-* range targeting, arbitrary breakpoints, custom breakpoint registration (v3 theme.screens vs v4 @theme --breakpoint-*), container queries (built-in v4 vs plugin v3), named containers, the full @3xs through @7xl scale, and container-query length units (cqw, cqh, cqi, cqb). Keywords: tailwind responsive, mobile-first, sm md lg xl 2xl, max-md, max-lg, arbitrary breakpoint, min-[400px], max-[800px], custom breakpoint, theme.screens, --breakpoint-md, @breakpoint, container query, @container, @container/name, named container, @sm @md @lg @xl @2xl @3xs @7xl, @tailwindcss/container-queries, container queries plugin, plugin deprecated v4, container query units, cqw, cqh, cqi, cqb, responsive layout broken on mobile, why does sm: hide my text, how do I add a custom breakpoint, container query not working, scoped responsive, intrinsic responsive, layout breakpoint vs container breakpoint.
license
MIT
compatibility
Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
Tailwind CSS Responsive Design
Two independent systems exist : viewport breakpoints (page-level) and
container queries (component-level). Use viewport breakpoints to change
layout based on the BROWSER size ; use container queries to change layout
based on a specific PARENT container's size.
Companion skills :
tailwind-syntax-utility-classes : the utilities you wrap in responsive prefixes
tailwind-syntax-variants : the full variant grammar (state, attribute, custom)
tailwind-core-v3-vs-v4 : the broader v3-to-v4 differences
Quick Reference : Default Viewport Breakpoints
Shared between v3 and v4 :
Prefix
Min width
CSS (v4)
CSS (v3)
sm
40rem / 640px
@media (width >= 40rem)
@media (min-width: 640px)
md
48rem / 768px
@media (width >= 48rem)
@media (min-width: 768px)
lg
64rem / 1024px
@media (width >= 64rem)
@media (min-width: 1024px)
xl
80rem / 1280px
@media (width >= 80rem)
@media (min-width: 1280px)
2xl
96rem / 1536px
@media (width >= 96rem)
@media (min-width: 1536px)
v4 emits modern range syntax (width >= 40rem). v3 emits classic
min-width. Functionally identical at runtime.
The Mobile-First Rule
Unprefixed utilities apply at ALL screen sizes. Prefixed utilities
(sm:, md:, lg:, etc.) apply at THAT breakpoint AND UP.
<!-- ALWAYS : center on mobile, left-align from 640px up --><pclass="text-center sm:text-left">Hello
Hello
</p>
<!-- NEVER : intended "center on small only" but actually applies from 640px up -->
<pclass="sm:text-center">
</p>
NEVER write sm:text-center thinking it means "small screens only". It
means "from sm breakpoint upward". To target small-only, use max-sm:.
Range Targeting With max-* Variants
Variant
CSS (v4)
Effective range
max-sm
@media (width < 40rem)
below 640px
max-md
@media (width < 48rem)
below 768px
max-lg
@media (width < 64rem)
below 1024px
max-xl
@media (width < 80rem)
below 1280px
max-2xl
@media (width < 96rem)
below 1536px
Stack with a min variant to target a SINGLE breakpoint range :
<!-- Applies at md only (768px to 1023px) --><divclass="md:max-lg:flex"></div><!-- Applies at md and lg (768px to 1279px) --><divclass="md:max-xl:bg-red-500"></div>
max-* was introduced in Tailwind v3.4 and remains available in v4 with
identical syntax.
Arbitrary Breakpoints
For one-off values not in the breakpoint scale, use bracket notation :
<divclass="min-[400px]:flex max-[600px]:hidden">
Visible from 400px up, hidden below 600px (so visible 600px to infinity).
</div><divclass="min-[1400px]:max-[1599px]:bg-yellow-200">
Yellow background only in the 1400px to 1599px range.
</div>
ALWAYS use rem (not px) in v4 to align with the rest of the v4 token
scale. NEVER mix rem and px in the same breakpoint set : it produces
inconsistent breakpoints when the user changes root font-size.
Without the plugin, @container and @sm:flex simply do not generate any
CSS in v3.
v4 : built-in (NEVER install the plugin)
/* src/app.css */@import"tailwindcss";
/* That's it. Container queries available immediately. */
The v3 plugin README explicitly notes : "As of Tailwind CSS v4.0, container
queries are supported in the framework by default and this plugin is no
longer required." Leaving the plugin in a v4 project is harmless but
useless dead weight.
The v3 plugin shipped fewer sizes (@xs through @7xl, 12 sizes, no
@3xs or @2xs). NEVER assume v3 has the full v4 scale.
Container Queries : Max and Range
<divclass="@container"><divclass="flex flex-row @max-md:flex-col">
Row by default, column when @container is BELOW @md.
</div></div>
Variant
CSS
@max-sm
@container (width < 24rem)
@max-md
@container (width < 28rem)
@max-lg
@container (width < 32rem)
@max-xl
@container (width < 36rem)
@max-2xl
@container (width < 42rem)
Range stacking :
<divclass="@container"><!-- Applies only when @container is between @sm and @md --><divclass="@sm:@max-md:bg-yellow-100"></div></div>
Container Queries : Named Containers
When nested @container parents exist, name them to target a specific one :
<divclass="@container/sidebar"><divclass="@container/card"><!-- React to the sidebar container's size --><pclass="text-sm @md/sidebar:text-base">Title</p><!-- React to the card container's size --><pclass="text-xs @lg/card:text-sm">Body</p></div></div>
ALWAYS name containers when they nest. Unnamed @md: targets the NEAREST
ancestor @container. Add a name to make the intent explicit.
NEVER use cqb or cqh without @container-size on a parent : block-size
containment is opt-in because the browser cost is higher than width-only.
Decision Tree : Viewport vs Container Query
Does the layout react to PAGE size (browser window)?
├── YES → Use viewport breakpoints : sm:flex md:grid-cols-2
│ Independent of where the component sits in the tree.
│
└── NO → Does the layout react to a SPECIFIC PARENT'S size?
├── YES → Use container queries : @container on parent, @md:flex-row on child.
│ Component-intrinsic ; renders correctly in any layout slot.
│
└── BOTH → Combine : @container the component, use both viewport
prefixes for page-level concerns AND @sm/@md for
container-local concerns. They compose with `:` between.
ALWAYS prefer container queries for reusable components (cards, sidebars,
nav items). ALWAYS use viewport breakpoints for page-level layout (grid
templates, header height).
v3 to v4 Migration : Container Queries
Two steps :
Remove @tailwindcss/container-queries from package.json devDependencies.
Remove require('@tailwindcss/container-queries') from the legacy
tailwind.config.js plugins array (if you kept a v3 config via @config).
Existing @container and @sm: class usage works without changes : the
v4 built-in implementation is API-compatible with the v3 plugin (plus the
two extra @3xs and @2xs sizes).
NEVER keep the plugin installed and active in v4 : it tries to register
the same variants and produces silent ordering oddities.
Reference Files
references/methods.md : every variant, every size, full breakpoint and
container query API
references/examples.md : side-by-side v3 vs v4 setup, named containers,
custom breakpoints, length units, real layouts
references/anti-patterns.md : mobile-first reversal, max-* range
confusion, named-container bleeding, plugin-left-in-v4, cqb without
@container-size
