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
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
